Change map

Optionalplugin: change-map

The change map plugin turns the review of a code change into a review of its architecture. A pull request, or a branch an agent finished, is shown as a diagram of the parts it touches and the interactions between them, rather than as a list of files. You see what the change does to the system first, and then open the code of any part, its lines highlighted in the diff.

When a diagram of parts is not enough, the agent adds sequence diagrams for the order of the calls and state diagrams for a lifecycle, so you review how the change behaves as well as what it touches. Parts of the interface carry screenshots before and after, or recordings of the part in use, so you see what the person using the software will see. Each comment goes back on a part, an interaction, lines of a file, an area of a screenshot, a moment of a recording or an entity of a diagram, so the agent knows exactly what it is about.

Click to enlarge

The ticket form selected, its file in the drawer, and a comment on three of its lines.

When to use it

• A pull or merge request that touches several parts of a system, read as a whole before you read it file by file.
• A change an agent made on its own, reviewed before it opens a pull request or merges.
• A change to an interface, with screenshots of each screen before and after, or a recording of how it behaves.
• A change to a flow or a lifecycle, such as a retry, a handshake or a new status, explained with sequence and state diagrams for a detailed architectural review.

To review the comments an agent wants to post on a pull request, use Code review instead.

Install

The plugin comes with the app. Install it in Settings › Plugins, or from the command line:

pinrail plugins install change-map

What you see

The map

Each part of the change, such as a component, a module, an endpoint or a table, is a card, and the cards are grouped into lanes such as Web app, API and Database. Each interaction between two parts is a line, labelled with what it does.

• A card shows the part’s kind and status in a header tinted with the status colour: new, changed, removed or unchanged. Under its title, a bar and two counts show the lines its part of the change adds and removes. A part of the interface also shows its first screenshot.
• An interaction’s label shows how many files implement it, so an interaction that no code implements has no count.
• The selected part has a thicker border in the accent colour.

The buttons in the map’s top-left corner zoom in and out, fit the map to the view, and switch to compact cards, which show the title and the status only. The choice of cards is kept as a setting.

The side panel

With nothing selected, the side panel shows the change as a whole:

• The change’s summary, its branches and a link to it, and how many of the change’s changed lines are on the map, not counting changelogs and lock files.
• The parts changed, each with a check on its icon once you have reviewed it and the number of its comments. Choosing one zooms the map in on it.
• The diagrams, and the other files, which no part or interaction names.
• The files of the change, in a drawer at the bottom of the panel. Each file shows its line counts and how many of its lines are off the map, and a filter narrows the list. Choosing a file opens it in the diff drawer and highlights the parts, interactions and diagram entities that touch it, while the rest of the map and the diagrams dims.

Selecting a part or an interaction shows its summary, its files, its screenshots, the diagrams it appears in and its comments instead. You can drag the panel’s left edge to make it wider.

The diff drawer

The diff drawer under the map shows the selected part’s files, with the lines that implement it highlighted. Selecting another part of the same file scrolls to its lines. A changed line that no part, interaction or diagram covers has an amber edge, and the drawer’s header counts those lines. The button in the header shows or hides the drawer, and the choice is kept as a setting.

Sequence and state diagrams

A change about the order of things or about a lifecycle is hard to read from a map of parts alone. For such a change, the agent adds diagrams of their own, each in a tab above the map. They are optional, and an agent adds one only when the change needs it.

• A sequence diagram shows the participants from left to right, with a lifeline under each, and the messages between them from top to bottom: calls, asynchronous messages, replies and messages to the sender itself. Frames mark the alternatives, the optional runs, the loops and the parallel runs.

Click to enlarge

A retried request answered with the ticket the first one created.

• A state diagram shows the states, with a dot for the start and a ringed dot for the end, and the transitions between them, labelled with their event, guard and action. It runs from left to right, and a button beside its zoom buttons lays it out from top to bottom instead. That choice is kept as a setting.

Click to enlarge

The Save button's states, with the transition back from a failed save selected.

Every participant, message, state and transition has a status, a summary and the files and lines that implement it, which open in the drawer, as a part of the map does. A participant or a message that stands for a part or an interaction of the map is the same thing as that part or interaction, so its files, comments and reviewed mark are shared and nothing is reviewed twice. The tabs show how many comments each diagram has.

Screenshots of interface changes

A part of the interface, such as a form or a page, can carry screenshots, each with a before and an after. The side panel shows each screen in turn, and a screenshot opens larger in the drawer:

• Side by side, the before and the after at the same zoom and position, so a detail lines up across both.
• With a slider over the two, which you drag to wipe from the before to the after.
• The after alone, at the drawer’s full width.

You zoom with the scroll wheel or to the actual pixels, pan with the hand tool or by holding Space, and drag a box over any area to comment on it. The comment goes back with the area’s position on the image, and the choice of comparison is kept as a setting.

Click to enlarge

The ticket form before and after, with a comment on the spinner in the Save button.

Recordings of interface changes

When a change is about how the interface behaves over time, such as a spinner or a sequence of steps, a screen can be a recording of the part in use instead, an MP4, MOV or WebM file. The side panel shows its first frame with a play mark, and the drawer plays it, with a scrubber and the time.

Comment on this frame pauses the recording and comments on the frame at the playhead, and a box dragged on the video comments on an area of that frame. Each comment marks the scrubber at its moment, and its box shows while the playhead is there. In the side panel, a recording’s comment names its moment, and choosing it opens the recording there.

Comments and reviewed marks

• Comments go on a part, an interaction, a line or a range of lines in the drawer, an area of a screenshot, a moment of a recording or an area of its frame, and an entity of a diagram. The field stays at the bottom of the side panel. Badges on the map, the tabs and the files count the comments.
• Reviewed marks are set on each part, interaction or entity you have read, and go back to the agent. The header counts the parts and interactions the change adds, changes or removes that you have reviewed. Clicking the count goes to the next one left.

You choose Approve or Request changes in the header. Until you choose, comments ask for changes, and a review with none approves. With comments and Approve, the hand-over says Approve with comments.

The keys are N and P to move between parts, Enter to open the selection’s first file, C to comment on it, R to mark it reviewed, U to go to the next part or interaction left to review and F to fit the diagram to the view. Esc closes the drawer.

To see it before any agent asks with it, send its sample: pinrail submit change-map --sample, or Send a sample in its details in Settings › Plugins.

Asking from your agent

The plugin ships a skill that tells an agent how to build a map from a change: how to work out the parts and their interactions, choose the line ranges, add screenshots and decide when a diagram helps, with a script that lists the change’s files from git and one that notes what a map leaves out before it is submitted. Turn it on with the switch under Skill in the plugin’s details in Settings › Plugins. An agent you connected in Settings › Agents then has it in its pinrail skill, and any other agent can read it with pinrail plugins skill change-map. Your instructions only need to say when to use it:

AGENTS.md

When a change is complex, submit it for review with the `change-map` Pinrail plugin.

What the agent sends

map.json

{
  "change": { "title": "Dedup tickets on save", "source": "fix/ticket-dedup", "target": "main" },
  "summary": "A second press of **Save** no longer creates a second ticket.",
  "lanes": [{ "id": "web", "title": "Web app" }, { "id": "api", "title": "API" }],
  "nodes": [
    { "id": "ticket-form", "title": "Ticket form", "kind": "ui", "lane": "web", "status": "changed",
      "changes": [{ "file": "web/src/TicketForm.tsx", "lines": [[40, 68]] }],
      "screens": [{ "title": "Save while saving",
                    "before": { "$attachment": "form-before.png" },
                    "after": { "$attachment": "form-after.png" } }] },
    { "id": "tickets-endpoint", "title": "POST /tickets", "kind": "endpoint", "lane": "api",
      "changes": [{ "file": "lib/helpdesk_web/controllers/ticket_controller.ex" }] }
  ],
  "edges": [{ "id": "post", "from": "ticket-form", "to": "tickets-endpoint", "label": "POST /tickets" }],
  "files": [{ "path": "web/src/TicketForm.tsx", "status": "modified", "diff": "@@ -38,20 +38,31 @@ …" }]
}

• nodes are the parts of the change. A part’s kind sets its icon, its status its colour, and its changes the files and line ranges that implement it.
• edges are the interactions between parts, such as calls, events or imports.
• files holds the unified diff of each changed file. A file that no part or interaction names is listed in the panel as one of the other files.
• screens hold screenshots of an interface part, before and after, or a recording of it as video, each sent with --attach and named as {"$attachment": "<name>"}.
• diagrams are optional sequence and state diagrams, whose participants and messages can name a part with node and an interaction with edge.

What comes back

{
  "verdict": "request_changes",
  "comments": [
    { "target": { "node": "tickets-endpoint" }, "body": "Return the id of the existing ticket with the 409." },
    { "target": { "file": "web/src/TicketForm.tsx", "start_line": 47, "line": 49, "side": "new" },
      "body": "Keep the key after a failed save." },
    { "target": { "diagram": "save-button", "item": "t4" }, "body": "Show why the save failed." }
  ],
  "reviewed": ["ticket-form", "post"]
}

Field	What the agent does with it
verdict	approve: goes on, and reads any comments as notes. request_changes: applies the comments in a new version.
comments[].target	What the comment is about: a part (node), an interaction (edge), lines of a file (file, line, start_line and side), an area of a screenshot (screen and region, in fractions of the image, with pixels and image_size giving the same area in the image’s own pixels), a moment of a recording (screen with the image video, and time in seconds, with an area of its frame as for a screenshot when one is marked), or an entity of a diagram (diagram and item).
reviewed	The parts, interactions and diagram entities the person marked as reviewed.

Reference

The plugin’s manifest, and the schemas a payload and a decision are checked against, read from the plugin’s own files.

Manifestmanifest.jsonPayloadwhat the agent sendsDecisionwhat comes backSettingsSettings › Plugins

FieldsJSON

name	change-map
version	1.1.1
title	Change map
description	A code change, such as a pull request, drawn as a diagram of the parts it touches and how they interact. Each part opens its files in a diff viewer, and parts of the interface show screenshots before and after. Comment on a part, an interaction or a line, and approve the change or ask for changes.
use_when	You made or studied a code change with several moving parts, such as a feature across services, modules and screens, and the person should understand how the parts fit together before reading the diff, then approve it or say what to change.
attachments	.png .jpg .jpeg .webp .gif image/png image/jpeg image/webp image/gif .mp4 .m4v .mov .webm video/mp4 video/quicktime video/webm · up to 100 MB each, 32 a review
shortcuts	NSelect the next part PSelect the previous part EnterOpen the selected part's first file CComment on the selection RMark the selection as reviewed UGo to the next part or interaction to review FFit the diagram to the frame

• changeobject

  The change under review, such as a pull request.

  • refstring

    Its reference on the code host, such as #128 or !42.

    at most 80 chars

  • titlestring

    at most 300 chars

  • urlstring

    Its page on the code host.

    at most 2000 chars

  • sourcestring

    The branch with the change.

    at most 200 chars

  • targetstring

    The branch it goes into.

    at most 200 chars

  • descriptionstring

    Its description, in Markdown.

    at most 20000 chars

• summarystring

  What the change does and why, in Markdown. Shown before anything is selected.

  at most 20000 chars

• lanesobject[]

  Groups of related parts, drawn as bands, such as the web app, the API and the database.

  at most 12 items

  • idstringrequired

    1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

  • titlestringrequired

    1–80 chars

• nodesobject[]required

  The parts of the system the change touches, and parts it does not touch that help explain it.

  1–80 items

  • idstringrequired

    1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

  • titlestringrequired

    1–120 chars

  • kindenum

    What the part is: a screen or component, a module, a service, an endpoint, a store such as a table or a queue, a job, a third-party system, configuration or tests. Sets its icon.

    "ui" "module" "service" "endpoint" "store" "job" "external" "config" "test"

  • lanestring

    The id of the lane it belongs to.

    at most 80 chars

  • statusenum

    What the change does to it. context: a part the change does not touch.

    "added" "changed" "removed" "context" · default "changed"

  • summarystring

    What changed in this part and why, in Markdown.

    at most 20000 chars

  • changesobject[]

    The files that belong to this part, each optionally narrowed to line ranges on the new side.

    at most 200 items

    • filestringrequired

      A path in files.

      1–500 chars

    • linesarray[]

      Ranges of lines on the new side, each [first, last].

      at most 50 items

  • screensobject[]

    Screens of a user interface part: screenshots before and after the change, or one of them for a screen that is new or removed, or a recording of the part in use.

    at most 12 items

    • One of: before or after or video
    • titlestring

      at most 200 chars

    • beforefile
    • afterfile
    • videofile

      A recording of the part in use, such as an MP4 or a WebM screen capture, in place of screenshots.

• edgesobject[]

  How the parts interact.

  at most 200 items

  • idstringrequired

    1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

  • fromstringrequired

    The id of the node it starts from.

    at most 80 chars

  • tostringrequired

    The id of the node it goes to.

    at most 80 chars

  • labelstring

    at most 120 chars

  • kindenum

    A request and its response, a read or a write, a message or a notification, a code dependency, or a component that draws another.

    "call" "data" "event" "import" "render"

  • statusenum

    "added" "changed" "removed" "unchanged" · default "changed"

  • summarystring

    What changed in this interaction, in Markdown.

    at most 20000 chars

  • detailobject

    The shapes that cross the edge, shown as code.

    • requeststring

      at most 20000 chars

    • responsestring

      at most 20000 chars

  • changesobject[]

    The files that belong to this part, each optionally narrowed to line ranges on the new side.

    at most 200 items

    • filestringrequired

      A path in files.

      1–500 chars

    • linesarray[]

      Ranges of lines on the new side, each [first, last].

      at most 50 items

• diagramsobject[]

  Optional diagrams beside the map, for a change about order or lifecycle more than structure. Add one only when the map alone does not explain the change.

  at most 12 items

  • idstringrequired

    1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

  • kindenumrequired

    sequence: participants and the messages between them, in order. state: states and the transitions between them.

    "sequence" "state"

  • titlestringrequired

    1–120 chars

  • summarystring

    What the diagram shows, in Markdown.

    at most 20000 chars

  • participantsobject[]

    A sequence's participants, from left to right.

    at most 20 items

    • idstringrequired

      1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

    • titlestringrequired

      1–120 chars

    • kindenum

      What the part is: a screen or component, a module, a service, an endpoint, a store such as a table or a queue, a job, a third-party system, configuration or tests. Sets its icon.

      "ui" "module" "service" "endpoint" "store" "job" "external" "config" "test"

    • nodestring

      The map part it is. Comments, files and the reviewed mark are then the part's.

      at most 80 chars

    • statusenum

      What the change does to it. context or unchanged: something the change leaves alone.

      "added" "changed" "removed" "context" "unchanged" · default "changed"

    • summarystring

      What changed in it and why, in Markdown.

      at most 20000 chars

    • changesobject[]

      The files that belong to this part, each optionally narrowed to line ranges on the new side.

      at most 200 items

      • filestringrequired

        A path in files.

        1–500 chars

      • linesarray[]

        Ranges of lines on the new side, each [first, last].

        at most 50 items

  • messagesobject[]

    A sequence's messages, from top to bottom.

    at most 200 items

    • idstringrequired

      1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

    • fromstringrequired

      The id of the participant that sends it.

      at most 80 chars

    • tostringrequired

      The id of the participant that receives it.

      at most 80 chars

    • labelstring

      at most 160 chars

    • kindenum

      "call" "async" "reply" "self" · default "call"

    • edgestring

      The map interaction it is. Comments, files and the reviewed mark are then the interaction's.

      at most 80 chars

    • statusenum

      What the change does to it. context or unchanged: something the change leaves alone.

      "added" "changed" "removed" "context" "unchanged" · default "changed"

    • summarystring

      What changed in it and why, in Markdown.

      at most 20000 chars

    • changesobject[]

      The files that belong to this part, each optionally narrowed to line ranges on the new side.

      at most 200 items

      • filestringrequired

        A path in files.

        1–500 chars

      • linesarray[]

        Ranges of lines on the new side, each [first, last].

        at most 50 items

  • groupsobject[]

    Frames around a run of a sequence's messages.

    at most 40 items

    • idstringrequired

      1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

    • kindenumrequired

      "alt" "opt" "loop" "par"

    • labelstring

      at most 160 chars

    • firststringrequired

      The id of the first message in the frame.

      at most 80 chars

    • laststringrequired

      The id of the last message in the frame.

      at most 80 chars

  • statesobject[]

    A state diagram's states.

    at most 60 items

    • idstringrequired

      1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

    • titlestring

      at most 120 chars

    • kindenum

      "state" "initial" "final" · default "state"

    • statusenum

      What the change does to it. context or unchanged: something the change leaves alone.

      "added" "changed" "removed" "context" "unchanged" · default "changed"

    • summarystring

      What changed in it and why, in Markdown.

      at most 20000 chars

    • changesobject[]

      The files that belong to this part, each optionally narrowed to line ranges on the new side.

      at most 200 items

      • filestringrequired

        A path in files.

        1–500 chars

      • linesarray[]

        Ranges of lines on the new side, each [first, last].

        at most 50 items

  • transitionsobject[]

    A state diagram's transitions.

    at most 200 items

    • idstringrequired

      1–80 chars · matches ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

    • fromstringrequired

      at most 80 chars

    • tostringrequired

      at most 80 chars

    • labelstring

      Its event, guard and action, as you write them.

      at most 160 chars

    • statusenum

      What the change does to it. context or unchanged: something the change leaves alone.

      "added" "changed" "removed" "context" "unchanged" · default "changed"

    • summarystring

      What changed in it and why, in Markdown.

      at most 20000 chars

    • changesobject[]

      The files that belong to this part, each optionally narrowed to line ranges on the new side.

      at most 200 items

      • filestringrequired

        A path in files.

        1–500 chars

      • linesarray[]

        Ranges of lines on the new side, each [first, last].

        at most 50 items

• filesobject[]required

  Every changed file with its unified diff, as git diff prints it.

  1–500 items

  • pathstringrequired

    1–500 chars

  • statusenum

    "added" "modified" "deleted" "renamed"

  • wasstring

    The old path of a renamed file.

    at most 500 chars

  • diffstringrequired

    at most 2000000 chars

• verdictenumrequired

  approve: go ahead with the change. request_changes: change it as the comments say, then send a new round.

  "approve" "request_changes"

• commentsobject[]required

  at most 500 items

  • targetany | any | any | any | any | anyrequired

    What a comment is on: a node, an edge, a line of a file or lines from start_line to line on the same side, an area of a screenshot, a moment of a recording or an area of its frame, or an entity of an extra diagram.

    • One of: node or edge or file + line or screen + region or screen + time or diagram + item
    • nodeany
    • edgeany
    • fileany
    • lineany
    • sideany
    • start_lineany
    • screenany
    • regionany
    • diagramany
    • itemany
    • pixelsany
    • image_sizeany
    • timeany
  • bodystringrequired

    1–20000 chars

• reviewedstring[]

  The nodes, edges and diagram entities (as <diagram>:<item>) the person marked as reviewed.

  at most 300 items

• show_diffbooleanShow the diff drawer

  Open a review with the diff drawer showing, as you left it last.

  default false

• card_stylestringCards

  How the map draws each part: with its kind and status in a header and the lines it changes, or as a compact card.

  "detailed" Detailed · "compact" Compact · default "detailed"

• state_directionstringState diagrams

  Which way a state diagram runs from its first state.

  "LR" Left to right · "TB" Top to bottom · default "LR"

• screen_modestringScreenshot comparison

  How a part's screenshots open when it has a before and an after

  "side" Side by side · "wipe" Slider · "after" After only · default "side"

• panel_widthintegerSide panel width

  The side panel's width in pixels, as you last dragged it.

  340–2000 · default 340