sar/.claude/skills/bmad-checkpoint-preview/step-02-walkthrough.md

Step 2: Walkthrough

Display: Orientation → [Walkthrough] → Detail Pass → Testing

Follow Global Step Rules in SKILL.md

• Organize by concern, not by file. A concern is a cohesive design intent — e.g., "input validation," "state management," "API contract." One file may appear under multiple concerns; one concern may span multiple files.
• The walkthrough activates design judgment, not correctness checking. Frame each concern as "here's what this change does and why" — the human evaluates whether it's the right approach for the system.

BUILD THE WALKTHROUGH

Identify Concerns

With Suggested Review Order (full-trail mode — the normal path, including when step-01 generated a trail):

1. Read the Suggested Review Order stops from the spec (or from conversation context if generated by step-01 fallback).
2. Resolve each stop to a file in the current repo. Output in path:line format per the standing rule.
3. Read the diff to understand what each stop actually does.
4. Group stops by concern. Stops that share a design intent belong together even if they're in different files. A stop may appear under multiple concerns if it serves multiple purposes.

Without Suggested Review Order (fallback when trail generation failed, e.g., git unavailable):

1. Get the diff against the appropriate baseline (same rules as step 1).
2. Identify concerns by reading the diff for cohesive design intents:
   • Functional groupings — what user-facing behavior does each cluster of changes support?
   • Architectural layers — does the change cross boundaries (API → service → data)?
   • Design decisions — where did the author choose between alternatives?
3. For each concern, identify the key code locations as path:line stops.

Order for Comprehension

Sequence concerns top-down: start with the highest-level intent (the "what and why"), then drill into supporting implementation. Within each concern, order stops so each one builds on the previous. The reader should never encounter a reference to something they haven't seen yet.

If the change has a natural entry point (e.g., a new public API, a config change, a UI entry point), lead with it.

Write Each Concern

For each concern, produce:

1. Heading — a short phrase naming the design intent (not a file name, not a module name).
2. Why — 1–2 sentences: what problem this concern addresses, why this approach was chosen over alternatives. If the spec documents rejected alternatives, reference them here.
3. Stops — each stop on its own line: path:line followed by a brief phrase (not a sentence) describing what this location does for the concern. Keep framing under 15 words per stop.

Target 2–5 concerns for a typical change. A single-concern change is fine — don't invent groupings. A change with more than 7 concerns is a signal the scope may be too large, but present it anyway.

PRESENT

Output the full walkthrough as a single message with this structure:

Orientation → [Walkthrough] → Detail Pass → Testing

Then each concern group using this format:

### {Concern Heading}

{Why — 1–2 sentences}

- `path:line` — {brief framing}
- `path:line` — {brief framing}
- ...

End the message with:

---

Take your time — click through the stops, read the diff, trace the logic. While you are reviewing, you can:
- "run advanced elicitation on the error handling"
- "party mode on whether this schema migration is safe"
- or just ask anything

When you're ready, say **next** and I'll surface the highest-risk spots.

EARLY EXIT

If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:

• If they want to approve and ship → read fully and follow ./step-05-wrapup.md
• If they want to reject and rework → read fully and follow ./step-05-wrapup.md
• If you misread them → acknowledge and continue the current step.

NEXT

Default: read fully and follow ./step-03-detail-pass.md