From db04465c8b5386b50dee90c21814ddf2feebc46e Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 12 Mar 2026 14:48:21 -0400 Subject: [PATCH 1/2] feat(bugfix): add /speedrun command for running remaining phases without stopping Add a speedrun command that auto-advances through the bugfix workflow from the current phase to the end, using artifact detection to determine where to pick up. The command replaces the controller for the duration of the run, dispatching one phase at a time and looping via re-reads. To support this without breaking the existing stop-and-wait behavior: - Update all 8 phase skills to use generic "return to dispatcher" endings instead of hardcoding the controller path, with both controller and speedrun shown as examples - Update the controller announce step to include its path as the dispatcher so skills can find their way back - Speedrun announces itself as dispatcher on each phase entry, creating breadcrumbs in conversation context that skills use to return to the right file Made-with: Cursor --- workflows/bugfix/.claude/commands/speedrun.md | 172 ++++++++++++++++++ .../bugfix/.claude/skills/assess/SKILL.md | 4 +- .../bugfix/.claude/skills/controller/SKILL.md | 12 +- .../bugfix/.claude/skills/diagnose/SKILL.md | 4 +- .../bugfix/.claude/skills/document/SKILL.md | 2 +- workflows/bugfix/.claude/skills/fix/SKILL.md | 4 +- workflows/bugfix/.claude/skills/pr/SKILL.md | 2 +- .../bugfix/.claude/skills/reproduce/SKILL.md | 4 +- .../bugfix/.claude/skills/review/SKILL.md | 2 +- workflows/bugfix/.claude/skills/test/SKILL.md | 4 +- 10 files changed, 192 insertions(+), 18 deletions(-) create mode 100644 workflows/bugfix/.claude/commands/speedrun.md diff --git a/workflows/bugfix/.claude/commands/speedrun.md b/workflows/bugfix/.claude/commands/speedrun.md new file mode 100644 index 00000000..5209a1b3 --- /dev/null +++ b/workflows/bugfix/.claude/commands/speedrun.md @@ -0,0 +1,172 @@ +--- +description: Speed-run the remaining bugfix phases without stopping between them. +displayName: speedrun +icon: ⚡ +--- + +# /speedrun — Run the Remaining Workflow + +You are in **speedrun mode**. Run the next incomplete phase, then return here +for the next one. Do not use the controller (`.claude/skills/controller/SKILL.md`). + +## User Input + +```text +$ARGUMENTS +``` + +Consider the user input before proceeding. It may contain a bug report, issue +URL, context about where they are in the workflow, or instructions about which +phases to include or skip. + +## How Speedrun Works + +Each time you read this file, you will: + +1. Determine which phase to run next (see "Determine Next Phase" below) +2. If all phases are done, print the completion report and stop +3. Otherwise, execute that one phase (see "Execute a Phase" below) +4. The phase skill will tell you to return to the file that dispatched it — + that's this file (`.claude/commands/speedrun.md`). Re-read it and repeat. + +This loop continues until all phases are complete or an escalation stops you. + +## Determine Next Phase + +Check which phases are already done by looking for artifacts and conversation +context, then pick the first phase that is NOT done. + +### Phase Order and Completion Signals + +| Phase | Skill | "Done" signal | +| ------- | ------- | --------------- | +| assess | `.claude/skills/assess/SKILL.md` | Conversation contains a bug assessment (summary, gaps, plan) | +| reproduce | `.claude/skills/reproduce/SKILL.md` | `artifacts/bugfix/reports/reproduction.md` exists | +| diagnose | `.claude/skills/diagnose/SKILL.md` | `artifacts/bugfix/analysis/root-cause.md` exists | +| fix | `.claude/skills/fix/SKILL.md` | `artifacts/bugfix/fixes/implementation-notes.md` exists | +| test | `.claude/skills/test/SKILL.md` | `artifacts/bugfix/tests/verification.md` exists | +| review | `.claude/skills/review/SKILL.md` | Always run once between test and document | +| document | `.claude/skills/document/SKILL.md` | `artifacts/bugfix/docs/pr-description.md` exists | +| pr | `.claude/skills/pr/SKILL.md` | A PR URL has been shared in conversation | + +### Rules + +- Check artifacts in order. The first phase whose signal is NOT satisfied is next. +- If no artifacts exist and no assessment has been done, start at **assess**. +- If the user specifies a starting point in `$ARGUMENTS`, respect that. +- If conversation context clearly establishes a phase was completed (even + without an artifact), skip it. + +## Execute a Phase + +1. **Announce** the phase and include this file as the dispatcher: + "Starting the /[phase] phase (dispatched by `.claude/commands/speedrun.md` — speedrun mode)." +2. **Read** the phase skill from the table above +3. **Execute** the skill's steps +4. The skill will tell you to announce which file you are returning to and + re-read it. Return to **this file** (`.claude/commands/speedrun.md`). + +## Speedrun Rules + +- **Do not stop and wait between phases.** After each phase, return here and + continue to the next one. +- **Do not read the controller.** This command replaces the controller for this + run. If you are tempted to read `.claude/skills/controller/SKILL.md`, read + `.claude/commands/speedrun.md` instead. +- **DO still follow CLAUDE.md escalation rules.** If a phase hits an + escalation condition (confidence below 80%, unclear root cause after + investigation, multiple valid solutions with unclear trade-offs, security or + compliance concern, architectural decision needed), stop and ask the user. + After the user responds, re-read this file to resume. + +## Phase-Specific Notes + +### assess + +- If no bug report or issue URL exists in `$ARGUMENTS` or conversation, ask + the user once, then proceed. +- Present the assessment inline but do not wait for confirmation. + +### reproduce + +- If reproduction fails, note the failure and continue to diagnose anyway + (diagnosis may reveal why reproduction is difficult). + +### diagnose + +- If multiple root causes are plausible and you cannot determine which is + correct with high confidence, this is an escalation point — stop and ask. + +### fix + +- Create a feature branch if one doesn't exist yet. +- If the diagnosis identified multiple fix approaches with unclear trade-offs, + this is an escalation point — stop and ask. + +### test + +- Run the full test suite. If tests fail due to your fix, attempt to resolve + them before continuing. +- If failures persist after a reasonable attempt, note them and continue — + review will catch outstanding issues. + +### review + +- Always run this phase between test and document. +- **Verdict: "fix and tests are solid"** — continue to document. +- **Verdict: "fix is adequate, tests incomplete"** — attempt to add the + missing tests, then continue to document. +- **Verdict: "fix is inadequate"** — perform **one** revision cycle: go back + to fix → test → review. If the second review still says "inadequate," stop + and report the issues to the user instead of looping further. + +### document + +- Generate all documentation artifacts per the skill. + +### pr + +- Follow the PR skill's full process including its fallback ladder. +- If PR creation fails after exhausting fallbacks, report and stop. + +## Completion Report + +When all phases are done (or if you stop early due to escalation), present: + +```markdown +## Speedrun Complete + +### Phases Run +- [each phase that ran and its key outcome] + +### Artifacts Created +- [all artifacts with paths] + +### Result +- [PR URL, or reason for stopping early] + +### Notes +- [any escalations, skipped phases, or items needing follow-up] +``` + +## Usage Examples + +**From the beginning (no prior work):** + +```text +/speedrun Fix bug https://github.com/org/repo/issues/425 - session status updates failing +``` + +**Mid-workflow (some phases already done):** + +```text +/speedrun +``` + +The command detects existing artifacts and picks up from the next incomplete phase. + +**With an explicit starting point:** + +```text +/speedrun Start from /fix — I already know the root cause +``` diff --git a/workflows/bugfix/.claude/skills/assess/SKILL.md b/workflows/bugfix/.claude/skills/assess/SKILL.md index 4c19eebb..b3cd1fb2 100644 --- a/workflows/bugfix/.claude/skills/assess/SKILL.md +++ b/workflows/bugfix/.claude/skills/assess/SKILL.md @@ -143,6 +143,6 @@ Report your assessment: - Your understanding of the bug - Key gaps or risks identified - -Then **re-read the controller** (`.claude/skills/controller/SKILL.md`) for next-step guidance. - Your proposed plan + +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/controller/SKILL.md b/workflows/bugfix/.claude/skills/controller/SKILL.md index e4555c94..80794fac 100644 --- a/workflows/bugfix/.claude/skills/controller/SKILL.md +++ b/workflows/bugfix/.claude/skills/controller/SKILL.md @@ -38,13 +38,15 @@ Phases can be skipped or reordered at the user's discretion. ## How to Execute a Phase -1. **Announce** the phase to the user before doing anything else, e.g., "Starting the /fix phase." - This is very important so the user knows that the workflow is working and learns about the commands. +1. **Announce** the phase to the user before doing anything else. Include this + file as the dispatcher so skills know where to return, e.g., + "Starting the /fix phase (dispatched by `.claude/skills/controller/SKILL.md`)." + This is very important so the user knows the workflow is working, learns + about the commands, and so skills can find their way back here. 2. **Read** the skill file from the list above 3. **Execute** the skill's steps directly — the user should see your progress -4. When the skill is done, it will tell you to report your findings and - re-read this controller. Do that — then use "Recommending Next Steps" - below to offer options. +4. When the skill is done, it will report its findings and re-read this + controller. Then use "Recommending Next Steps" below to offer options. 5. Present the skill's results and your recommendations to the user 6. **Stop and wait** for the user to tell you what to do next diff --git a/workflows/bugfix/.claude/skills/diagnose/SKILL.md b/workflows/bugfix/.claude/skills/diagnose/SKILL.md index bfba77db..c22149e2 100755 --- a/workflows/bugfix/.claude/skills/diagnose/SKILL.md +++ b/workflows/bugfix/.claude/skills/diagnose/SKILL.md @@ -116,6 +116,6 @@ Report your findings: - The identified root cause (or top hypotheses if uncertain) - Confidence level in the diagnosis - -Then **re-read the controller** (`.claude/skills/controller/SKILL.md`) for next-step guidance. - Where the root cause analysis was written + +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/document/SKILL.md b/workflows/bugfix/.claude/skills/document/SKILL.md index 6e6813f5..b29d933b 100644 --- a/workflows/bugfix/.claude/skills/document/SKILL.md +++ b/workflows/bugfix/.claude/skills/document/SKILL.md @@ -165,4 +165,4 @@ Report your results: - What documents were created and where - Any gaps flagged for later -Then **re-read the controller** (`.claude/skills/controller/SKILL.md`) for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/fix/SKILL.md b/workflows/bugfix/.claude/skills/fix/SKILL.md index b1b106ae..3b6d091d 100755 --- a/workflows/bugfix/.claude/skills/fix/SKILL.md +++ b/workflows/bugfix/.claude/skills/fix/SKILL.md @@ -133,6 +133,6 @@ Report your results: - What was changed (files, approach) - What quality checks passed - -Then **re-read the controller** (`.claude/skills/controller/SKILL.md`) for next-step guidance. - Where the implementation notes were written + +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/pr/SKILL.md b/workflows/bugfix/.claude/skills/pr/SKILL.md index a10a76c9..7d80f9f7 100644 --- a/workflows/bugfix/.claude/skills/pr/SKILL.md +++ b/workflows/bugfix/.claude/skills/pr/SKILL.md @@ -598,4 +598,4 @@ Report your results: - What was included - Any follow-up actions needed (mark ready for review, add reviewers, etc.) -Then **re-read the controller** (`.claude/skills/controller/SKILL.md`) for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/reproduce/SKILL.md b/workflows/bugfix/.claude/skills/reproduce/SKILL.md index eb416da1..512dc27d 100644 --- a/workflows/bugfix/.claude/skills/reproduce/SKILL.md +++ b/workflows/bugfix/.claude/skills/reproduce/SKILL.md @@ -88,6 +88,6 @@ Report your findings: - Whether the bug was successfully reproduced - Key observations and environment details - -Then **re-read the controller** (`.claude/skills/controller/SKILL.md`) for next-step guidance. - Where the reproduction report was written + +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/review/SKILL.md b/workflows/bugfix/.claude/skills/review/SKILL.md index 5362310d..cf80e742 100644 --- a/workflows/bugfix/.claude/skills/review/SKILL.md +++ b/workflows/bugfix/.claude/skills/review/SKILL.md @@ -191,4 +191,4 @@ are insufficient, say what's missing. Your verdict and recommendation (from Step 5) serve as the phase summary. -Then **re-read the controller** (`.claude/skills/controller/SKILL.md`) for next-step guidance. +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/test/SKILL.md b/workflows/bugfix/.claude/skills/test/SKILL.md index 7e973202..8b218aa8 100755 --- a/workflows/bugfix/.claude/skills/test/SKILL.md +++ b/workflows/bugfix/.claude/skills/test/SKILL.md @@ -155,6 +155,6 @@ Report your results: - How many tests were added and their results - Whether the full test suite passes - -Then **re-read the controller** (`.claude/skills/controller/SKILL.md`) for next-step guidance. - Where the verification report was written + +Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/commands/speedrun.md` for next phase.") and **re-read that file** for next-step guidance. From 0655d24a46c68b366eb7ed79d1c854e0a7464203 Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 12 Mar 2026 19:04:25 -0400 Subject: [PATCH 2/2] feat(bugfix): add durable artifacts for assess and review phases The assess and review phases previously had no persistent artifacts, relying on conversation state to determine completion. This breaks resumability across session restarts. - Assess skill now writes artifacts/bugfix/reports/assessment.md - Review skill now writes artifacts/bugfix/review/verdict.md - Speedrun command updated to check these artifacts instead of conversation state for phase completion detection Made-with: Cursor --- workflows/bugfix/.claude/commands/speedrun.md | 6 +++--- workflows/bugfix/.claude/skills/assess/SKILL.md | 10 +++++++++- workflows/bugfix/.claude/skills/review/SKILL.md | 10 +++++++++- 3 files changed, 21 insertions(+), 5 deletions(-) diff --git a/workflows/bugfix/.claude/commands/speedrun.md b/workflows/bugfix/.claude/commands/speedrun.md index 5209a1b3..ca254a78 100644 --- a/workflows/bugfix/.claude/commands/speedrun.md +++ b/workflows/bugfix/.claude/commands/speedrun.md @@ -40,19 +40,19 @@ context, then pick the first phase that is NOT done. | Phase | Skill | "Done" signal | | ------- | ------- | --------------- | -| assess | `.claude/skills/assess/SKILL.md` | Conversation contains a bug assessment (summary, gaps, plan) | +| assess | `.claude/skills/assess/SKILL.md` | `artifacts/bugfix/reports/assessment.md` exists | | reproduce | `.claude/skills/reproduce/SKILL.md` | `artifacts/bugfix/reports/reproduction.md` exists | | diagnose | `.claude/skills/diagnose/SKILL.md` | `artifacts/bugfix/analysis/root-cause.md` exists | | fix | `.claude/skills/fix/SKILL.md` | `artifacts/bugfix/fixes/implementation-notes.md` exists | | test | `.claude/skills/test/SKILL.md` | `artifacts/bugfix/tests/verification.md` exists | -| review | `.claude/skills/review/SKILL.md` | Always run once between test and document | +| review | `.claude/skills/review/SKILL.md` | `artifacts/bugfix/review/verdict.md` exists | | document | `.claude/skills/document/SKILL.md` | `artifacts/bugfix/docs/pr-description.md` exists | | pr | `.claude/skills/pr/SKILL.md` | A PR URL has been shared in conversation | ### Rules - Check artifacts in order. The first phase whose signal is NOT satisfied is next. -- If no artifacts exist and no assessment has been done, start at **assess**. +- If no artifacts exist, start at **assess**. - If the user specifies a starting point in `$ARGUMENTS`, respect that. - If conversation context clearly establishes a phase was completed (even without an artifact), skip it. diff --git a/workflows/bugfix/.claude/skills/assess/SKILL.md b/workflows/bugfix/.claude/skills/assess/SKILL.md index b3cd1fb2..91b85f95 100644 --- a/workflows/bugfix/.claude/skills/assess/SKILL.md +++ b/workflows/bugfix/.claude/skills/assess/SKILL.md @@ -131,9 +131,17 @@ Deliver your assessment in this structure: Be direct. If the bug report is clear and complete, say so. If it's vague or missing critical details, say that too. +### Step 7: Write the Assessment Artifact + +Save your assessment to `artifacts/bugfix/reports/assessment.md` so that +subsequent phases (and speedrun resumption) can detect that this phase is +complete. The file should contain the same content you presented to the user +in Step 6. + ## Output -- Assessment presented directly to the user (inline, not a file artifact) +- Assessment presented directly to the user (inline) +- Assessment saved to `artifacts/bugfix/reports/assessment.md` - The project repository cloned and available for subsequent phases - No code is executed, no files in the project are modified diff --git a/workflows/bugfix/.claude/skills/review/SKILL.md b/workflows/bugfix/.claude/skills/review/SKILL.md index cf80e742..2b4772cc 100644 --- a/workflows/bugfix/.claude/skills/review/SKILL.md +++ b/workflows/bugfix/.claude/skills/review/SKILL.md @@ -159,9 +159,17 @@ Be direct. Don't hedge with "everything looks great but maybe consider..." when there's an actual problem. If the fix is broken, say so. If the tests are insufficient, say what's missing. +### Step 6: Write the Review Artifact + +Save your verdict and findings to `artifacts/bugfix/review/verdict.md` so that +subsequent phases (and speedrun resumption) can detect that this phase is +complete. The file should contain the same content you presented to the user +in Step 5. + ## Output -- Review findings reported directly to the user (inline, not a file) +- Review findings reported directly to the user (inline) +- Review saved to `artifacts/bugfix/review/verdict.md` - If issues are found, specific guidance on what to fix or test next ## Usage Examples