diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md index 5563dfcad..847d94616 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md @@ -1,7 +1,7 @@ --- wipFile: '{implementation_artifacts}/spec-wip.md' deferred_work_file: '{implementation_artifacts}/deferred-work.md' -spec_file: '' # set at runtime for plan-code-review before leaving this step +spec_file: '' # set at runtime for both routes before leaving this step --- # Step 1: Clarify and Route @@ -53,6 +53,8 @@ Never ask extra questions if you already understand what the user intends. 5. Route — choose exactly one: **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. + 1. Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`. + **EARLY EXIT** → `./step-oneshot.md` **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path. diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md index da8a0e256..19ff6b58e 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md @@ -1,5 +1,6 @@ --- deferred_work_file: '{implementation_artifacts}/deferred-work.md' +spec_file: '' # set by step-01 before entering this step --- # Step One-Shot: Implement, Review, Present @@ -29,19 +30,55 @@ Deduplicate all review findings. Three categories only: If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding. +### Generate Spec Trace + +Write `{spec_file}` with the following content: + +1. **Frontmatter** — same schema as the full spec template, plus `route: 'one-shot'`: + ```yaml + --- + title: '{title derived from intent}' + type: '{feature | bugfix | refactor | chore}' + created: '{date}' + status: 'done' + route: 'one-shot' + --- + ``` + +2. **Title and Intent** — the `# {title}` heading followed by an `## Intent` section with **Problem** and **Approach** lines (2–3 sentences total). This is the same summary you already generated for the terminal — reuse it. + +3. **Suggested Review Order** — append as a `## Suggested Review Order` section. Build using the same convention as step-05: + - Order stops by concern, not by file. Lead with the entry point. + - Every code reference is a clickable spec-file-relative link. Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format: `[short-name:line](../../path/to/file.ts#L42)` with a `#L` line anchor. The relative path must be dynamically derived — never hardcode the depth. + - Each stop gets one ultra-concise line of framing (≤15 words). + - When there is only one concern, omit the bold label — just list the stops directly. + + Format each stop as framing first, link on the next indented line: + + ```markdown + ## Suggested Review Order + + - {one-line framing} + [`file.ts:42`](../../src/path/to/file.ts#L42) + ``` + + > The `../../` prefix above is illustrative — compute the actual relative path from `{spec_file}`'s directory to each target file. + ### Commit If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip. ### Present -1. Open all changed files in the user's editor so they can review the code directly: - - Resolve two sets of absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) each changed file. Run `code -r "{absolute-root}" ` — the root first so VS Code opens in the right context, then each changed file. Always double-quote paths to handle spaces and special characters. - - If `code` is not available (command fails), skip gracefully and list the file paths instead. +1. Open the spec in the user's editor so they can click through the Suggested Review Order: + - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters. + - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead. 2. Display a summary in conversation output, including: - The commit hash (if one was created). - - List of files changed with one-line descriptions. Use CWD-relative paths with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/`. + - List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths. - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so. + - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order. + - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop." 3. Offer to push and/or create a pull request. HALT and wait for human input.