From af00f542dc81833699ff20cc233b3af75d0c04ac Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Mon, 16 Mar 2026 19:00:21 -0600 Subject: [PATCH] feat(quick-dev): add Review Trail generation to step 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .../step-05-present.md | 31 ++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md index 800394015..619fff202 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md @@ -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.