feat(quick-dev): add Review Trail generation to step 5

Step 5 now builds a concern-ordered trail of clickable path:line stops
with brief framing and appends it to the spec before committing. The
trail is a standalone review artifact — useful without any skill.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alex Verkhovsky 2026-03-16 19:00:21 -06:00
parent e5062a8bbb
commit af00f542dc
1 changed files with 30 additions and 1 deletions

View File

@ -10,8 +10,37 @@
## INSTRUCTIONS
### Generate Review Trail
Before committing, append a `## Review Trail` section to `{spec_file}` after the last existing section. This is a post-implementation artifact — do not modify the Code Map.
Read `{baseline_commit}` from `{spec_file}` frontmatter. Construct the diff of all changes since `{baseline_commit}`. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed.
Build the trail as an ordered sequence of **stops** — clickable `path:line` references with brief framing — optimized for a human reviewer reading top-down to understand the change:
1. **Order by concern, not by file.** Group stops by the conceptual concern they address (e.g., "validation logic", "schema change", "UI binding"). A single file may appear under multiple concerns.
2. **Lead with the entry point** — the place a reviewer should look first to understand the design intent.
3. **End with peripherals** — tests, config, types, and other supporting changes come last.
4. **Every code reference uses `path:line` format** so editors auto-link them.
5. **Each stop gets one line of framing** — what this code does in the context of the change and why. No paragraphs.
Format:
```markdown
## Review Trail
### {Concern Name}
- `path/to/file.ts:42` — {one-line framing}
- `path/to/other.ts:17` — {one-line framing}
### {Next Concern}
- `path/to/file.ts:88` — {one-line framing}
```
### Commit and Present
1. Change `{spec_file}` status to `done` in the frontmatter.
2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request.
3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes — mention that `{spec_file}` contains a Review Trail with clickable `path:line` stops for navigating the change. Offer to push and/or create a pull request.
Workflow complete.