From 3980e578855ffdc1687dc140e5d39c4885f5a2c1 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sun, 29 Mar 2026 14:55:09 -0600 Subject: [PATCH] feat(quick-dev): one-shot route generates spec trace file (#2121) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(quick-dev): generate spec trace file for one-shot route One-shot changes now leave a lightweight spec file with frontmatter, intent summary, and suggested review order — eliminating numbering gaps when quick-dev is used as the primary dev loop. Co-Authored-By: Claude Opus 4.6 (1M context) * refactor(quick-dev): reference spec template instead of inlining structure Co-Authored-By: Claude Opus 4.6 (1M context) * refactor(quick-dev): deduplicate slug derivation and clarify title variable Extract shared slug derivation logic above the route fork in step-01 so both one-shot and plan-code-review routes use a single instruction block. Add explicit title variable assignment in step-oneshot before it is referenced in the Generate Spec Trace section. --------- Co-authored-by: Claude Opus 4.6 (1M context) --- .../step-01-clarify-and-route.md | 6 ++++-- .../bmad-quick-dev/step-oneshot.md | 21 +++++++++++++++---- 2 files changed, 21 insertions(+), 6 deletions(-) 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..5f802c960 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 @@ -52,11 +52,13 @@ Never ask extra questions if you already understand what the user intends. - On **K**: Proceed as-is. 5. Route — choose exactly one: + 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`. + **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. + **EARLY EXIT** → `./step-oneshot.md` **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path. - 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`. ## NEXT 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..b6384159a 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,31 @@ 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 + +Set `{title}` = a concise title derived from the clarified intent. + +Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others: + +1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`. +2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal. +3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing). + ### 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.