Walkthrough

walkthrough — Phase 2: The Walkthrough Plan

Once the agent finishes execution and verification, it outputs a walkthrough artifact: a single Markdown file that lets you quickly catch up on what was changed and what is proven to work, and lets you do a staging-check with Git before merging.

This is modeled on Google Antigravity's walkthrough plan: the agent is expected to prove the change works (unit tests + real browser behavior), capture visual evidence, and hand you a review gate — not just dump a diff.

When to use

• After /goal (or any implementation) plus its verification pass are complete — e.g., after /review-it / /verify / manual testing
• Before /ship-it, as the last checkpoint before commit/PR/merge
• User says "walkthrough", "生成 walkthrough", "生成走查文档", "write the walkthrough", "/walkthrough", "Phase 2 walkthrough"

The Job

1. Determine the change scope — which feature / Issue / branch is being walked through, and which repos it spans
2. Write the plain-language opening — before/after + why, readable by someone who has never seen the code
3. Write the Change Summary — the technical detail, for whoever will read the diff next
4. Run and record Verification Steps — execute the tests and commands, capture real output, label each claim's provenance
5. Capture Visual Proof — screenshot / record the UI behavior you verified
6. Build the Review Gate — stage-check the diff with Git, draft the PR description, spell out deploy-order prerequisites
7. Save to tasks/ and present — write walkthrough-[feature].md, render it to HTML, summarize for the user

Section-by-section

1. 先说人话 / Plain-language opening (读前必读)

The first thing in the file. A PM, QA, a neighbouring team, or you in three months must be able to read only this section and know what changed and why they should care.

Required content:

• Before / after, concretely — what the caller/user sees, not what the code does:

  	改之前	改之后
  {用户/调用方看到什么}	{old behaviour}	{new behaviour}

• Why it changed — 2–3 reasons in plain words. If you cannot state a reason without naming a class, a flag, or a table, you do not understand the change well enough to write this section.

• What the reader must do differently, if anything (call a new endpoint, run a migration, change the client).

Rules:

• Never open with an identifier. dryRun, draft_id, PriorityResolver are not explanations. Introduce the concept in plain words first, name it second.
• A sentence like "X 从「A」改为「B」" is banned unless A and B are both explained in plain words.
• If the change has a user-visible effect, describe it from the user's side.

BAD  (技术上没错，但读的人解不开)
> 把优先级的写入时机从「即时落库」改为「先返回 draft_id、确认后落库」

GOOD (同一件事)
> 用户改任务优先级时，以前客户端发一次就直接写进数据库；现在后端先把可选的优先级算出来
> 让用户挑一个，挑完才写。用户没挑就不写。

1b. Glossary — only if the doc uses internal jargon

If the doc uses any of: internal flag/field names (dryRun), numeric interface ids (1001), domain terms an outsider can't decode (「归一化」「草稿」), or module names not inferable from the file tree — add a two-column mapping from the doc's wording to plain language.

| 文中说法 | 说人话 |
|---|---|
| `dryRun` | 开关：`true` = 只算不写，不传 = 老行为 |
| 「草稿」 | 算出来、还没落库的中间结果 |

• Do not gloss standard terms (HTTP, SQL, PR) — that reads as padding.
• Pay special attention to pairs that look alike but mean different things. If two similarly-named concepts are easy to confuse, say so explicitly in the table — that is where readers actually get lost.

2. Change Summary

The technical description, for a reader who is about to open the diff. This is where identifiers belong — the plain-language section already paid for them.

• Read the diff (git diff, git log) and the Issue/PRD it serves
• Summarize in 3–6 bullets: what was built, refactored, added, or removed
• List the key files and components, and the shape of what's new (modules, pages, APIs, data structures)
• State the requirement it satisfies and link the Issue / PRD if present

3. Verification Steps

Proof that the implementation actually works — evidence, not assertion. Record what you ran and what it output.

• Terminal commands & unit tests: run the test suite (or the targeted tests), lint/build, and any smoke commands. Paste the exact command and its successful output (truncate noise, keep pass counts).

  go test ./... -run TestPriority

  ok  	github.com/example/app 0.042s

• Automated browser testing outcomes (if the change has UI): open the app in a sandbox/headless browser, click through the demo path, and record the outcome. For each scenario: the action performed, the observed result, pass/fail.

  Scenario: user sets a task's priority
    1. open /tasks — renders list
    2. click priority select on task #3 → pick "High"
    3. reload — task still shows High  ✓

• If a step was skipped (no tests, no UI), say so explicitly — don't invent evidence.

Label the provenance of every claim. Three levels, and say which one applies:

Never present 代码推断 or 未验证 as if it were 已实测. A walkthrough that overstates its evidence is worse than one with gaps, because the gaps are what the reader would have checked.

Record how you made the command run at all. If it needed a workaround — offline mode, a config override, an init script, a narrowed test filter — record it, otherwise the reader cannot reproduce your evidence.

./gradlew test --offline --rerun -I /tmp/no-failfast.gradle \
  --tests "com.example.tasks.*" --console=plain
# 依赖仓库在本机不可达，必须加 --offline；构建脚本设了 failFast=true，
# 不覆盖的话第一条失败就停，看不到完整清单

Also record a baseline caveat whenever the runner's defaults would mislead: failFast hiding later failures, a test cache replaying stale results (--rerun), a suite that is already red before your change.

If the broader suite is red, trace every failure — do not write "unrelated". For each one, give:

• the file/class, the commit that last touched it, and its date
• whether that commit is an ancestor of your base (→ pre-existing)
• whether it falls inside your own commit range (→ yours)

| 失败用例 | 所属类最后修改提交 | 是 base 祖先？ | 在本分支提交内？ |
|---|---|---|---|
| `PriorityResolverTest > defaultsToNormal()` | `1a2b3c4d` 2026-01-15 | 是 | 否 |

A failure traceable to a commit before your base is pre-existing — say so with the hash, so the reader can re-check. A failure inside your range is yours, however unrelated it looks.

4. Visual Proof

Screenshots or short screen recordings captured during browser testing, embedded directly into the file so it renders anywhere (GitHub, VS Code, browser).

• Screenshots: capture during the browser walkthrough above. Embed as base64 data URIs for a fully self-contained file (recommended):

  ![Task priority — set to High](data:image/png;base64,<base64>)

  On macOS you can capture a window with screencapture; for web pages prefer browser automation tooling (e.g. Playwright: npx playwright screenshot <url> tasks/shot.png, then read the PNG and embed it).
• Recordings: if you captured a screen recording, note its path and link it in the file (![Demo](tasks/recording-demo.mov)).
• Prefer 2–4 focused screenshots that prove the demo path (before → action → after), not a screenshot dump.
• If the change has no visual surface, write "None — change is backend/CLI only" rather than forcing a screenshot.

5. Review Gate

The final diff / PR description where you (or the user) staging-check the code with Git before merging.

• Diff stat + file list: git status, git diff --stat HEAD, git diff --name-status

• High-risk notes: call out force-pushed history, migrations, config changes, wide refactors, submodule pointer bumps

• Deploy-order prerequisites (required whenever the change ships a DDL / migration / config key / feature flag) — state (a) exactly what must be applied, (b) how (manual vs automatic), (c) the failure mode if the order is wrong:

  > `0042-add-priority-to-tasks.sql` 给 `tasks` 表加 `priority` 列。
  > **不会被任何 compose 自动执行**（唯一挂载的 initdb 目录指向的是另一个路径），
  > 必须手工应用到所有环境。实体已映射该列且 ddl-auto=none →
  > 代码先上线会让**每一次** Task 查询抛 SQLGrammarException，
  > 即整个服务的任务查询全挂，而非仅新功能不可用。

  "记得跑一下 migration" is not enough. The reader needs the blast radius, because that is what determines whether they schedule it carefully or wing it.

• Draft PR description: a ready-to-paste PR body (summary, test plan, Closes #N), mirroring /ship-it

• Merge checklist: confirm tests green, review pass done, no stray artifacts in git status, commit messages reference the Issue

Multi-repo changes. If the work spans more than one repo:

• one file list + verification section per repo, each with its own branch state (local == remote? pushed? PR open?)
• state explicitly that the branches must merge together, and what breaks if only one lands
• verify each repo's checkout individually. A repo you did not open is not a repo you verified — do not conclude "the other half isn't implemented" from a single checkout; the same repo often exists at several paths on different branches.