diff --git a/workflows/bugfix/.claude/commands/speedrun.md b/workflows/bugfix/.claude/commands/speedrun.md new file mode 100644 index 0000000..ca254a7 --- /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` | `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` | `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, 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 4c19eeb..91b85f9 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 @@ -143,6 +151,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 e4555c9..80794fa 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 bfba77d..c22149e 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 6e6813f..b29d933 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 b1b106a..3b6d091 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 a10a76c..7d80f9f 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 eb416da..512dc27 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 5362310..2b4772c 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 @@ -191,4 +199,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 7e97320..8b218aa 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.