From 0225dfd538364802be4ce14764222a3607408138 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Mon, 16 Mar 2026 23:21:00 -0600 Subject: [PATCH] refactor(quick-dev): sharpen Review Trail generation instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add intra-concern ordering (rule 3), ≤15 word framing budget (rule 6), and shift framing from description toward design rationale. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../bmad-quick-dev-new-preview/step-05-present.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) 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 619fff202..02c73ab33 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 @@ -12,17 +12,18 @@ ### 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. +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. +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 analysis of the working tree. 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. +2. **Lead with the entry point** — the single highest-leverage file:line a reviewer should look at first to grasp the design intent. +3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops. +4. **End with peripherals** — tests, config, types, and other supporting changes come last. +5. **Every code reference uses `path:line` format** so editors auto-link them. +6. **Each stop gets one ultra-concise line of framing** (≤15 words) — why this approach was chosen here and what it achieves in the context of the change. No paragraphs. Format: