/walkthrough

name: walkthrough
description: "Generate a Phase-2 Walkthrough artifact (walkthrough.md) once implementation and verification are complete. Captures a Change Summary, Verification Steps (commands + unit tests + automated browser testing outcomes), Visual Proof (screenshots/recordings embedded directly in the file), and a Review Gate (final diff + PR description for a Git staging-check) so you can catch up on what changed and what's proven to work before merging. Saves to tasks/walkthrough-[feature].md by default. Triggers on: /walkthrough, walkthrough, Phase 2 walkthrough, 生成 walkthrough, 生成走查文档, write the walkthrough."
user-invocable: true
# 本 skill 必须执行项目自己的测试/lint 命令去取真实证据，而命令因项目而异，故不限定 Bash 前缀。
allowed-tools:
  - Bash
metadata:
  author: smallnest
  version: 1.1.0

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 | |---|---|---| | **已实测**