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:

Label	Means	Example
已实测	You ran it, you have the output	95 PASSED / 0 FAILED
代码推断	Read from the code or a unit test, not executed	「没有优先级时回落 normal」（PriorityResolverTest 里有对应用例，但没跑）
未验证	Neither — and it must be said out loud	「本机无数据库/缓存/外部服务，服务级行为未在本环境验证」

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.

Output

Two files, same basename:

File	Role
tasks/walkthrough-[feature-name].md	Source. What you author and edit. Kebab-case, e.g. walkthrough-priority-system.md
tasks/walkthrough-[feature-name].html	Deliverable. What you hand to a reviewer. Generated from the .md, never hand-edited

The HTML is not optional — it is the artifact people actually read. It is light-themed (warm off-white, serif headings, terracotta accent), self-contained (no CDN, no external assets), and carries a fixed table-of-contents sidebar on the left built from the document's h2/h3.

Render it with the script bundled with this skill:

python3 scripts/md2html.py tasks/walkthrough-[feature-name].md
# or, once installed:
python3 ~/.claude/skills/walkthrough/scripts/md2html.py tasks/walkthrough-[feature-name].md

• Writes walkthrough-[feature-name].html beside the input; pass a second path to override.
• --title "…" overrides the page title (default: the document's # H1).
• Needs the markdown package: python3 -m pip install --user markdown. If it is missing the script exits with that instruction — relay it, do not silently skip the HTML.
• Embedded data: image URIs pass through untouched, so Visual Proof screenshots survive.
• Re-render after every edit to the .md. A stale HTML beside an updated Markdown is worse than no HTML: the reviewer reads the stale one.

If the user passes a name (/walkthrough user-auth) or an Issue number (/walkthrough #42), use that. If the current branch is feat/issue-42-* or feat/priority-system, derive the feature name from it. Otherwise ask.

Template

# Walkthrough — {Feature / Issue Title}

> Phase 2 walkthrough artifact · generated {date} · {author}
> {跨哪几个仓 / 分支名，若只有一仓则省略}

## Change Summary

### 先说人话：这次到底改了什么

{2–4 句，不含任何标识符。改之前什么样、改之后什么样。}

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

{为什么改，2–3 条大白话。}
{读的人需要做什么不同的事吗？}

### 术语表

| 文中说法 | 说人话 |
|---|---|
| {identifier / 数字接口号 / 领域词} | {plain meaning} |

### 技术摘要

{2–4 sentence high-level description — 到这里才允许出现标识符}

- {bullet: what was built/refactored/added/removed}
- {key files, components, pages, APIs}
- {requirement satisfied — link Issue/PRD}

## Verification Steps

### Terminal commands & unit tests

```bash
{exact command, including any workaround needed to make it run}
```
```
{actual output — pass counts, ok lines}
```

**provenance:** {已实测 / 代码推断 / 未验证} — {对每条重要结论标注}
{若跑不了：本机缺什么（DB/Redis/外部服务），因此哪一层未被验证}

{若更宽的测试面是红的，逐条列表并给出「是 base 祖先吗 / 在本分支内吗」}

### Automated browser testing

| # | Scenario | Action | Observed result | Status |
|---|----------|--------|-----------------|--------|
| 1 | {demo step} | {clicks / inputs} | {what happened} | ✅ / ❌ |

## Visual Proof

![{caption}](data:image/png;base64,{base64})

_{or: None — change is backend/CLI only}_

## Review Gate

```bash
git status
git diff --stat HEAD
git diff --name-status
```
{output}

### High-risk notes

{force-pushed history / migrations / config / submodule bumps}

**部署顺序前置** {仅当涉及 DDL / migration / 配置项 / 开关}
- 要应用什么：{文件路径}
- 怎么应用：{手工 / 自动；若「不会被任何东西自动执行」就直说}
- **顺序错了会怎样**：{blast radius，不是「功能不可用」而是「什么会一起挂」}

### Draft PR

{ready-to-paste PR body — Summary / Test plan / Closes #N}

### Merge checklist

- [ ] Unit tests / build pass (evidence in Verification Steps)
- [ ] Browser testing done where UI changed (evidence in Visual Proof)
- [ ] Review pass complete (/review-it)
- [ ] No stray artifacts in `git status`
- [ ] Commit messages reference the Issue
- [ ] 每条结论都标了 provenance（已实测 / 代码推断 / 未验证）
- [ ] 若有更宽测试面的红，逐条追溯到 commit 并说明是否在本次范围内
- [ ] 部署顺序前置已写清（含 blast radius），若有
- [ ] 多仓时：每个仓各自的文件清单/证据/分支状态都齐了

Determining the feature name

1. If the user provides it (/walkthrough user-auth), use it
2. If on a branch feat/issue-42-* / feat/priority-system / fix/issue-42-*, derive from the branch (strip the feat/ prefix and issue number)
3. If a PRD/SPEC exists in tasks/ (prd-*.md, spec-*.md), reuse its feature name
4. Otherwise ask: "What feature name should the walkthrough use?"

Edge cases

Scenario	Handling
No changes detected (git diff empty, nothing new)	Say so plainly; do not fabricate a walkthrough
No tests exist	Note "no automated tests in repo" and rely on manual/browser verification evidence
Change has no UI	Visual Proof = "None — backend/CLI only"; browser-testing section marked N/A
Screenshot embedding fails	Fall back to tasks/*.png relative paths and note the files to commit alongside
tasks/ directory missing	Auto-create it
Walkthrough already exists for this feature	Ask: update in place or overwrite? default = overwrite (fresh snapshot)
Verification couldn't be completed	Record it as a blocker in the Review Gate — never mark unverified work as proven
Broader test suite is red	Trace each failure to a commit (ancestor of base?) before writing anything. "unrelated" without a hash is not evidence
Change spans multiple repos	One section per repo + explicit "must merge together"; check each checkout — a repo you didn't open isn't verified
Change ships a DDL / migration / flag	Deploy-order prerequisite with blast radius is mandatory
Only part of the change is testable locally (no DB/Redis/external service)	Say which layer is unverified in this environment; a doc that overstates evidence is worse than one with declared gaps
Doc is heavy with internal identifiers	Add the plain-language opening + glossary. If the opening paragraph contains a flag name, it isn't written yet
markdown package not installed	Relay the script's install hint (python3 -m pip install --user markdown); do not silently skip the HTML
Markdown edited after rendering	Re-run the renderer. Never leave a stale .html next to a newer .md
Document will be shared outside the team / into a public repo	Replace every repo-specific example (paths, class/table/column names, commit hashes, internal hosts) with a neutral one before writing

Relationship to other skills

/goal → /review-it → /note-it → /walkthrough → /ship-it
   │         │           │           │             │
 execute   find/fix   rationale   proven +      commit + PR
                                  review gate

• /review-it — fixes issues and confirms the change is sound; walkthrough assumes this (or equivalent) already ran
• /note-it — captures design rationale per Issue; walkthrough captures proof + summary, complementary
• /understand — explains what new code does; walkthrough is the formal artifact you hand to a reviewer
• /ship-it — consumes the walkthrough: the Review Gate's draft PR and checklist feed straight into it

Checklist

Before saving:

• Plain-language opening exists and contains no identifiers — a non-engineer can read it standalone
• It says what changed before vs after, and why
• Glossary present if the doc uses internal ids / flags / domain jargon; confusable concept pairs called out
• Change Summary is written for a fresh reader (not a diff dump)
• Every Verification Step shows the actual command + actual output
• Where the command needed a workaround to run, that's recorded
• Every claim labelled 已实测 / 代码推断 / 未验证
• Red tests on the broader suite traced to a commit (hash + is-it-before-base), not hand-waved as "unrelated"
• Browser scenarios recorded with pass/fail outcomes, where UI exists
• Visual Proof embedded (base64) or explicit "None"
• Review Gate shows git status / git diff --stat + draft PR + merge checklist
• Deploy-order prerequisites + blast radius, if the change ships a migration/config/flag
• Multi-repo: every repo has its own file list, evidence, and branch state
• Unverified claims are marked as unverified — nothing invented
• Saved to tasks/walkthrough-[feature-name].md
• Rendered to .html and re-rendered after the last Markdown edit (left TOC sidebar present)
• No repo-internal specifics leaked into examples if this document is destined for a shared/public place