commit-tour

A commit guided tour is a JSON annotation of a commit's diff, stored in the git note ref shelley-tour. Shelley's diff UI shows a badge on annotated commits and renders the tour: important changes first with commentary, trivial changes collapsed.

Workflow

Annotate a commit right after making it. Delegate to a subagent when the commit is large; pass it the commit hash, the repo directory, and this skill.

Work files-first, then chunks: survey the changed files, plan the narrative order, and only then read patch bodies — selectively. Never print the full chunks JSON into your context for anything beyond a small commit.

1. Survey the commit with the chunk index:

   shelley tour chunks [-C <repo-dir>] -index <commit>
   

   This prints the commit subject and one line per suggested chunk — id, +adds/-dels, and @@ header — grouped by file, with no patch bodies. Chunks tagged [trivial: reason] are provably mechanical (generated files, whitespace-only hunks, renames, binaries): the scaffold already collapses them, so never read or comment on them. Classify the rest into tiers: data model / schema / API first, then core logic, tests, and finally boilerplate. Small edits are not pre-marked; judge those yourself.

2. Read only the chunks you need to write commentary for:

   shelley tour chunks [-C <repo-dir>] -text -only 4,7-9 <commit>
   shelley tour chunks [-C <repo-dir>] -text -only path/to/file.go <commit>
   

   -only takes chunk ids/ranges or a single file path. -text prints raw patch text with === chunk N <file> separators; without it you get JSON: the full hash, the commit subject, and a chunks array of {"id": <id>, "file": "...", "patch": "..."} objects. Each suggestion is a self-contained, git-apply-able fragment: its file headers plus one hunk, or the header block alone for a hunkless binary, rename, or mode change.

3. Write the tour JSON to a temp file. Start from a scaffold and reference suggested chunks by id — never re-type patch text:

   shelley tour scaffold [-C <repo-dir>] <commit> > tour.json
   

   The scaffold lists every chunk as a {"ref": <id>} entry in diff order, with generated files and mechanical hunks pre-marked trivial, so coverage is guaranteed by construction. Then reorder entries by importance, insert headers, and add comments:

   {
     "version": 1,
     "title": "Short plain-text title",
     "intro": "Markdown intro: what this commit does and why.",
     "decisions": [
       {"title": "One-line decision", "body": "Markdown: why, and what was rejected."}
     ],
     "questions": [
       {"title": "One-line question for the user?", "body": "Markdown context and options."}
     ],
     "chunks": [
       {"header": "## The data model"},
       {"ref": 4, "comment": "Why this shape matters."},
       {"patch": "diff --git a/server/model.go b/server/model.go\n...", "comment": "A hand-split slice."},
       {"header": "## The new screen"},
       {"media": "/tmp/after.png", "comment": "What to look at in this screenshot."},
       {"ref": 7, "comment": "The component that renders it."},
       {"header": "## Supporting changes"},
       {"ref": 0, "trivial": true},
       {"ref": 1, "trivial": true}
     ]
   }
   

   Every entry has exactly one of header, ref (a suggested-chunk id), patch (literal patch text, for hand-split hunks), or media (a path to a screenshot or recording). Ref and patch entries may also have comment and trivial; media entries may have comment, shown as the caption, and name, the label readers see (default: the file's base name). decisions and questions are optional; each item needs a one-line title and may have a body, both markdown. attach stores refs resolved to their patch text and media as git blobs, so the note remains self-contained.

   For big commits, edit the scaffold with a short script that maps ids to entries (e.g. add(14, 'comment'), header('## ...')) rather than rewriting it by hand.

4. Verify, then attach:

   shelley tour verify [-C <repo-dir>] <commit> tour.json
   shelley tour attach [-C <repo-dir>] <commit> tour.json
   

   verify applies all entries to the commit's parent tree and requires the exact commit tree. Gaps, overlaps, duplicate chunks, edited lines, or bad headers fail with Git's error text. attach verifies and writes the note (re-running overwrites; concurrent attaches are safe). shelley tour show <commit> prints an existing tour.

Writing a good tour

• Data model first. Open with changed types, schemas, formats, or APIs so readers understand the shapes involved.
• Important bits first. After the data model, order entries by importance, not file order: core logic and decisions, tests, then generated files, lock files, imports, boilerplate, and renames.
• Cover the whole diff. Verification reconstructs the commit tree from the parent, so every change must appear exactly once. Check ids off against the -index listing before verifying.
• Split large suggested hunks into logical patch entries by copying the file header block and rewriting each slice's @@ header. Old starts use parent coordinates; new starts use final-file coordinates. Zero context is fine. Keep each \ No newline at end of file marker with its hunk's last line.
• Entries may be reordered freely, including slices from the same original hunk.
• Mark boring patch entries "trivial": true; they render collapsed and need no comment.
• Use {"header": "## ..."} entries as markdown section headings.
• Comments are markdown. Explain why and what to notice rather than restating the diff; one to three sentences is usually enough.
• intro should state the problem, the approach, and the map of the tour.
• Amending changes the commit hash; re-attach the tour afterward.

Decisions, questions, and media

These are optional; include them when they help the reader, and omit them rather than padding.

• Key design decisions (decisions) record the non-obvious choices a reviewer would otherwise have to reverse-engineer or might second-guess: a data format, where state lives, a trade-off taken. Say why in the body and name the alternatives you rejected. Skip choices that follow directly from the task. Readers can comment on each one.
• Questions for the user (questions) are things you need the user to decide or confirm: unresolved trade-offs, assumptions you made, behavior you were unsure of. Phrase the title as a question that can be answered on its own, and put options or context in the body. Each question gets an Answer button whose reply lands in the user's message input, quoting it. Do not ask questions you could answer yourself by reading the code.
• Screenshots and recordings (media entries) show what a user-visible change looks like. When a commit changes UI, rendering, or other visual output, include the screenshots or short recordings you took while testing it, or that the browser tool can capture cheaply: the new state, before-and-after pairs, or a recording for interactions and animations. Don't build and launch an app only to photograph it. Place each next to the chunks it illustrates, use the comment to say what to look at, and give tool-named files (UUIDs) a descriptive name.
• Media must be PNG, JPEG, GIF, WebP, MP4, or WebM, at most 10 MiB each; keep recordings short. Relative paths resolve against the current directory, not -C.
• Readers comment on screenshots exactly like conversation images (drag a box around a region) and on recordings at the current playback time. Those comments name the git blob; git -C <repo> cat-file blob <hash> retrieves the file.
• attach stores media as git blobs pinned in the shelley-tour notes ref, so the note is self-contained and the original files may be deleted. Pins are permanent (notes history keeps them), and pushing the notes ref pushes them. Do not commit screenshots to the repository just for a tour.