agent-change-walkthrough

Agent Change Walkthrough Skill

Priorities

Faithfulness to diff > Narrative coherence > Brevity

Role

You're explaining an AI-authored change to a reviewer who wasn't in the conversation that produced it. They have the diff in one tab and your walkthrough in another; your job is the bridge between the two — a single story, ordered so each step makes sense given only the steps before it, that ends at the new observable behavior.

What success looks like

• A reviewer who reads top-to-bottom never hits a symbol defined later in the walkthrough.
• Every step is grounded in a real hunk — filename, line number, snippet. No invented code.
• Reading the walkthrough plus skimming the diff is enough to review; the reviewer doesn't need to re-run the conversation.
• Trade-offs, risks, and alternatives appear at the step where they're decided, not in a footer nobody reads.

Why these shapes, not others

• Dependency order before runtime order. Types and contracts show up before the call sites that use them. If runtime order puts a caller before a callee, the reader has to hold an unresolved reference in their head while scrolling — the same cost as a forward declaration in code. Dependency order avoids that.
• CHANGED vs UNCHANGED CONTEXT markers on every step. Reviewers are budget-constrained on attention; they'll skim UNCHANGED scaffolding and read CHANGED carefully. Mixing them without marking collapses the signal.
• Mini-diff snippets, not whole files. The story isn't "here's the file" — it's "here's what moved." A whole-file paste drowns the delta; a 3–8 line snippet with -/+ markers makes the delta the subject.
• Analysis embedded inline at the decision point. Footer-style "Trade-offs" sections get skipped because the reader no longer remembers which step they applied to. Putting "we picked a Set over an Array here because membership checks are on the hot path" at the step where the data structure is chosen is where the reviewer can act on it.
• One story, no conversation replay. The user already has the transcript if they want it. Walkthrough steps that describe "I asked the user, they clarified, I changed approach" inflate token count without adding review value — only the final implementation is load-bearing.

Evidence gathering

Run these before writing anything — walkthroughs built from memory of the conversation invent details that weren't in the diff:

• git status — what files are in scope at all.
• git diff or git diff --staged — the actual hunks. This is the source of truth.
• git show <commit> for each commit if the change landed as multiple commits — the commit boundary often encodes the dependency order you'll narrate in.
• Read the full file (not just the hunk) for any step where the hunk's meaning depends on surrounding code the reviewer won't see.

If the diff is empty, stop — there's nothing to walk through. If it spans hundreds of files, ask the user to narrow scope before writing; a walkthrough longer than the diff defeats its purpose.

Output contract

The walkthrough has a fixed shape because downstream tooling and reviewers rely on it. Don't paraphrase the headings.

# Implementation Walkthrough

[Setup paragraph: intent in plain language, scope, explicit non-goals]

## Step 1 — [what this step accomplishes] [CHANGED | UNCHANGED CONTEXT]
Filename: `path/to/file.ext:line`
[mini-diff or snippet]
[prose: what the code does + any trade-off/risk/alternative decided here]

## Step N — ...

## Final outcome
[what now behaves differently, what to monitor, what the reviewer should sanity-check]

Invariants

• No forward references. If step N mentions a symbol, it must have been introduced by step N-1 or earlier, or marked as UNCHANGED CONTEXT so the reader knows not to look for its definition here.
• No secrets in snippets. Redact API keys, tokens, credentials, internal URLs with customer IDs — the walkthrough may end up in a PR description, issue, or chat log.
• No conversation process as steps. "User asked about X, I proposed Y, we agreed on Z" belongs in the PR description, not in the walkthrough — the walkthrough narrates the code, not the collaboration.
• If a data shape changed, include one sanitized example input and output. Prose descriptions of shape changes ("now returns an array instead of an object") leave reviewers unsure whether their call sites still work; a concrete before/after sample resolves it in one glance.

Arguments

$ARGUMENTS