90 lines
4.1 KiB
Markdown
90 lines
4.1 KiB
Markdown
# 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`
|