bmad-template/.codebuddy/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`