diff --git a/docs/adr/2026-04-14-skill-invocation-cleanup.md b/docs/adr/2026-04-14-skill-invocation-cleanup.md new file mode 100644 index 00000000..b068be68 --- /dev/null +++ b/docs/adr/2026-04-14-skill-invocation-cleanup.md @@ -0,0 +1,294 @@ +# Proposal: Remove Manual Skill-Loading Boilerplate from Bugfix Workflow + +**Date:** 2026-04-14 +**Status:** Implemented +**Scope:** `workflows/bugfix/` (lessons may apply to other workflows later) + +## Context + +The bugfix workflow has 11 skills that coordinate through a controller (or +speedrun) orchestrator. During development, we discovered that the Ambient Code +Platform had a bug where the built-in skill invocation tool was not functioning. +Skills still *appeared* to work because the `systemPrompt` told the model where +skill files lived, and the model could load them with its file-reading tool and +follow the instructions manually. We engineered the workflow around this +workaround, adding explicit file-path references, dispatch blocks, and +return-and-re-read instructions throughout every skill. + +The platform bug has since been fixed. The skill tool now works correctly. But +the workaround scaffolding remains embedded in every skill file, adding +complexity, brittleness, and — critically — encouraging the agent to use the +file tool to load skills instead of the platform's native skill invocation +mechanism. + +### What the workaround looks like today + +Every phase skill (assess, reproduce, diagnose, fix, test, review, document) +contains two boilerplate blocks: + +**Dispatch block** (top of file): + +```markdown +## Dispatch + +If you were dispatched by the controller or by speedrun, continue below. +Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send +you back here with the proper workflow context. +``` + +**Return block** (bottom of file): + +```markdown +## When This Phase Is Done + +... + +Then announce which file you are returning to (e.g., "Returning to +`.claude/skills/controller/SKILL.md`." or "Returning to +`.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that +file** for next-step guidance. +``` + +The controller and speedrun skills contain complementary instructions: + +**Controller** — "How to Execute a Phase": + +```markdown +2. **Read** the skill file from the list above. You MUST call the Read tool on + the skill's `SKILL.md` file before executing. +``` + +**Speedrun** — "Execute a Phase": + +```markdown +2. **Read** the phase skill from the table above +... +4. The skill will tell you to announce which file you are returning to and + re-read it. Return to **this file** (`.claude/skills/speedrun/SKILL.md`). +``` + +Both orchestrators also list every phase with its full file path (e.g., +`.claude/skills/assess/SKILL.md`), which the agent uses as an argument to the +Read tool. + +### Why this is problematic + +1. **It bypasses the skill tool.** The instructions explicitly tell the agent to + use the Read tool on `SKILL.md` files. This was necessary when the skill tool + was broken, but now it means the agent is not using the platform's native + skill invocation, which may handle context management, scoping, and lifecycle + differently (and better) than raw file reading. + +2. **It's not portable.** Different runners (Claude Code, Gemini CLI, Cursor, + etc.) may expose skills through different mechanisms. Hardcoding "read + `.claude/skills/foo/SKILL.md`" assumes a specific file layout and a specific + tool for loading it. A portable workflow should say *which* skill to run, not + *how* to load it. + +3. **The return-and-re-read pattern is fragile.** Telling the agent to "re-read + this file for next-step guidance" after every phase is a workaround for the + fact that the controller wasn't being invoked as a skill. When the skill tool + works correctly, the orchestrator (controller or speedrun) should naturally + retain context after a sub-skill completes — there's no need to re-read + anything. + +4. **It adds ~20 lines of boilerplate per skill.** Across 11 skills, that's + ~200 lines of dispatch/return scaffolding that obscures the actual workflow + logic. + +5. **It confuses the agent.** The instructions create an unusual execution model + where the agent must track which file "dispatched" it and manually navigate + back. This is error-prone and was one of the main sources of reliability + issues during testing. + +## Proposal + +### Principle: say *what* to run, not *how* to run it + +The orchestrator skills (controller and speedrun) should tell the agent which +skill to run next by name. They should not tell the agent how to load or invoke +that skill. The agent (or its runner) knows how to run skills — that's a +platform capability, not a workflow concern. + +### Changes to orchestrator skills (controller, speedrun) + +**Current pattern:** + +```markdown +1. **Assess** (`/assess`) — `.claude/skills/assess/SKILL.md` +... +2. **Read** the skill file from the list above. You MUST call the Read tool on + the skill's `SKILL.md` file before executing. +... +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. +``` + +**Proposed pattern:** + +```markdown +1. **Assess** (`/assess`) — `assess` skill +... +2. **Run** the skill for the current phase. +... +4. When the skill completes, use "Recommending Next Steps" below to offer + options. +``` + +Specifically: + +- Replace file paths (`.claude/skills/assess/SKILL.md`) with skill names + (`assess` skill) in phase listings +- Remove instructions about using the Read tool to load skills +- Remove instructions about the agent returning to or re-reading the + orchestrator file +- Keep phase descriptions, gating rules, and recommendation logic unchanged + +### Changes to phase skills (assess, reproduce, diagnose, fix, test, review, document, pr, summary) + +**Remove the dispatch block entirely.** When a skill is invoked through the +skill tool, it doesn't need to know who invoked it or redirect to another skill +if invoked "incorrectly." The skill should just do its job. + +**Remove the return block's re-read instruction.** When a skill completes, it +should report its results. It doesn't need to tell the agent to go back and +re-read the controller. The orchestrator will naturally resume after the +sub-skill completes. + +**Keep the results reporting.** The "When This Phase Is Done" section should +still list what findings to report — that's genuinely useful guidance. Just +remove the "announce which file you are returning to and re-read that file" +part. + +### Changes to ambient.json systemPrompt + +**Current:** + +```json +"systemPrompt": "You are Amber, an expert colleague for systematic bug resolution.\n\nAt the start of the session, read .claude/skills/controller/SKILL.md — it defines the workflow phases, how to execute them, and how to recommend next steps." +``` + +**Proposed:** + +```json +"systemPrompt": "You are Amber, an expert colleague for systematic bug resolution.\n\nAt the start of the session, run the controller skill — it defines the workflow phases, how to execute them, and how to recommend next steps." +``` + +Change "read `.claude/skills/controller/SKILL.md`" to "run the controller +skill." + +### Changes to CLAUDE.md + +**Current:** + +```markdown +All phases are implemented as skills at `.claude/skills/{name}/SKILL.md`. +The workflow controller at `.claude/skills/controller/SKILL.md` manages phase +transitions and recommendations. The `/speedrun` skill at +`.claude/skills/speedrun/SKILL.md` runs all remaining phases without stopping. +``` + +**Proposed:** + +```markdown +All phases are implemented as skills. The controller skill manages phase +transitions and recommendations. The speedrun skill runs all remaining phases +without stopping. +``` + +Remove file paths; refer to skills by name. + +## Files affected + +| File | Change | +|------|--------| +| `.ambient/ambient.json` | Replace file path with skill name in `systemPrompt` | +| `CLAUDE.md` | Replace file paths with skill names | +| `.claude/skills/controller/SKILL.md` | Replace file paths with skill names in phase list; remove Read tool instructions; remove re-read-on-return instructions | +| `.claude/skills/speedrun/SKILL.md` | Same as controller | +| `.claude/skills/assess/SKILL.md` | Remove dispatch block; simplify "When This Phase Is Done" | +| `.claude/skills/reproduce/SKILL.md` | Same | +| `.claude/skills/diagnose/SKILL.md` | Same | +| `.claude/skills/fix/SKILL.md` | Same | +| `.claude/skills/test/SKILL.md` | Same | +| `.claude/skills/review/SKILL.md` | Same | +| `.claude/skills/document/SKILL.md` | Same | +| `.claude/skills/pr/SKILL.md` | Remove "return to coordinating skill and re-read" | +| `.claude/skills/summary/SKILL.md` | Remove conditional return-and-re-read | + +Total: 13 files, all within `workflows/bugfix/`. + +## What this does NOT change + +- **Phase logic.** The actual steps within each skill (how to diagnose, how to + write tests, etc.) are untouched. Only dispatch/return boilerplate is removed. +- **Gating rules.** The controller's `AskUserQuestion` gates between phases + remain. Speedrun's hard gates (e.g., assess PR gate) remain. +- **Artifact paths.** All `artifacts/bugfix/` references stay as-is. +- **Recommendation logic.** The controller's next-step recommendations are + unchanged. +- **Escalation rules.** `CLAUDE.md` escalation triggers are unchanged. +- **The orchestration model itself.** Controller and speedrun still orchestrate + phase skills. This proposal only changes how they *invoke* those skills (by + name instead of by file path + Read tool). + +## Risks + +### The agent might not find skills by name alone + +If the runner doesn't properly index skills, the agent might not know how to +invoke a skill called "assess." Mitigation: test in ACP before merging. If the +skill tool doesn't resolve names reliably, we can add a mapping hint (e.g., +"the `assess` skill at `assess/SKILL.md`") without prescribing the invocation +mechanism. + +### The skill tool might handle context differently + +When a skill is invoked via the skill tool (vs. read with the file tool), the +context management may differ — the skill's content might be scoped differently, +or the agent might not retain the orchestrator's context after the skill +completes. Mitigation: test the full controller flow end-to-end. If context +loss is an issue, we may need to keep a lighter version of the return guidance. + +### Behavioral regression from removing dispatch blocks + +The dispatch block served a secondary purpose: if a user invoked a phase skill +directly (e.g., by saying "/diagnose" without going through the controller), the +dispatch block redirected them to the controller first. Without it, a directly- +invoked skill will just execute without workflow context. This may actually be +fine — the skill still works standalone, and the controller is still available +if the user wants guided flow. + +## Testing plan + +1. **Validate JSON** — `ambient.json` parses correctly after edit +2. **Skill resolution** — Verify the agent can find and invoke each skill by + name in ACP +3. **Full controller flow** — Run a bug fix from assess through PR using the + controller, confirming phase transitions work without re-read instructions +4. **Speedrun flow** — Run a full speedrun and confirm it progresses through + all phases +5. **Direct skill invocation** — Invoke a phase skill directly (e.g., + "/diagnose") and confirm it works standalone +6. **Edge cases** — Test the review → fix → test → review loop in speedrun + mode; test `/summary` mid-workflow + +## Decisions on open questions + +1. **Skill names vs. slash-command names:** Use skill names — "the `assess` + skill." Slash-command syntax might bias the agent toward looking for a + command file instead of using the skill tool. + +2. **Speedrun's phase table:** Remove file paths entirely; use only skill names. + The agent shouldn't know where the files are — knowing paths encourages it + to load files directly instead of using the skill tool. Keep the completion + signals (artifact existence checks) in the table. + +3. **README.md:** Leave as-is. The README is documentation for humans and agents + that need to *modify* the workflow, which is a legitimate reason to know + file paths and load files directly. + +4. **Controller's "Always read skill files" rule:** Drop entirely. The + controller already tells the agent when to run each skill as part of the + phase execution flow. A separate general rule restating this is redundant + and was really just reinforcing the Read-tool workaround. diff --git a/workflows/bugfix/.ambient/ambient.json b/workflows/bugfix/.ambient/ambient.json index 975beefe..40fc8b81 100644 --- a/workflows/bugfix/.ambient/ambient.json +++ b/workflows/bugfix/.ambient/ambient.json @@ -1,6 +1,6 @@ { "name": "Fix a bug", "description": "Systematic workflow for analyzing, fixing, and verifying software bugs with comprehensive testing and documentation. Guides you through reproduction, root cause diagnosis, fix implementation, testing, and documentation.", - "systemPrompt": "You are Amber, an expert colleague for systematic bug resolution.\n\nAt the start of the session, read .claude/skills/controller/SKILL.md — it defines the workflow phases, how to execute them, and how to recommend next steps.", + "systemPrompt": "You are Amber, an expert colleague for systematic bug resolution.\n\nAt the start of the session, run the controller skill — it defines the workflow phases, how to execute them, and how to recommend next steps.", "startupPrompt": "Greet the user as Amber, their bug fix assistant. Explain that you'll guide them through systematic bug resolution: assess the report, reproduce the bug, diagnose root cause, implement the fix, test it, and document everything. Ask them to describe the bug or paste a bug report or issue URL to get started." } diff --git a/workflows/bugfix/.claude/skills/assess/SKILL.md b/workflows/bugfix/.claude/skills/assess/SKILL.md index 8688b2a1..fb78dd25 100644 --- a/workflows/bugfix/.claude/skills/assess/SKILL.md +++ b/workflows/bugfix/.claude/skills/assess/SKILL.md @@ -5,14 +5,6 @@ description: Understand the bug report and propose a plan before taking action. # Assess Bug Report Skill -## Dispatch - -If you were dispatched by the controller or by speedrun, continue below. -Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send -you back here with the proper workflow context. - ---- - You are reviewing a bug report to build a shared understanding with the user before any work begins. This is the first phase of the bugfix workflow. Your job is to read, think, and explain — not to start fixing anything. @@ -215,5 +207,3 @@ Report your assessment: - Your understanding of the bug - Key gaps or risks identified - Your proposed plan - -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.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 3456b416..27ce2a90 100644 --- a/workflows/bugfix/.claude/skills/controller/SKILL.md +++ b/workflows/bugfix/.claude/skills/controller/SKILL.md @@ -10,31 +10,31 @@ executing phases and handling transitions between them. ## Phases -1. **Assess** (`/assess`) — `.claude/skills/assess/SKILL.md` +1. **Assess** (`/assess`) — the `assess` skill Read the bug report, summarize your understanding, identify gaps, propose a plan. -2. **Reproduce** (`/reproduce`) — `.claude/skills/reproduce/SKILL.md` +2. **Reproduce** (`/reproduce`) — the `reproduce` skill Confirm the bug exists by reproducing it in a controlled environment. -3. **Diagnose** (`/diagnose`) — `.claude/skills/diagnose/SKILL.md` +3. **Diagnose** (`/diagnose`) — the `diagnose` skill Trace the root cause through code analysis, git history, and hypothesis testing. -4. **Fix** (`/fix`) — `.claude/skills/fix/SKILL.md` +4. **Fix** (`/fix`) — the `fix` skill Implement the minimal code change that resolves the root cause. -5. **Test** (`/test`) — `.claude/skills/test/SKILL.md` +5. **Test** (`/test`) — the `test` skill Write regression tests, run the full suite, and verify the fix holds. -6. **Review** (`/review`) — `.claude/skills/review/SKILL.md` +6. **Review** (`/review`) — the `review` skill Critically evaluate the fix and tests — look for gaps, regressions, and missed edge cases. -7. **Document** (`/document`) — `.claude/skills/document/SKILL.md` +7. **Document** (`/document`) — the `document` skill Create release notes, changelog entries, and team communications. -8. **PR** (`/pr`) — `.claude/skills/pr/SKILL.md` +8. **PR** (`/pr`) — the `pr` skill Push the branch to a fork and create a draft pull request. -9. **Summary** (`/summary`) — `.claude/skills/summary/SKILL.md` +9. **Summary** (`/summary`) — the `summary` skill Scan all artifacts and present a synthesized summary of findings, decisions, and status. Can also be invoked at any point mid-workflow. @@ -42,20 +42,13 @@ 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. 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 available phases, and so skills can find their way back here. -2. **Read** the skill file from the list above. You MUST call the Read tool on - the skill's `SKILL.md` file before executing. If you find yourself executing - a phase without having read its skill file, you are doing it wrong — stop - and read it now. -3. **Execute** the skill's steps directly — the user should see your progress -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. **Use `AskUserQuestion` to get the user's decision.** Present the +1. **Announce** the phase to the user before doing anything else, so the user + knows the workflow is working and learns about the available phases. +2. **Run** the skill for the current phase. +3. When the skill completes, use "Recommending Next Steps" below to offer + options. +4. Present the skill's results and your recommendations to the user. +5. **Use `AskUserQuestion` to get the user's decision.** Present the recommended next step and alternatives as options. Do NOT continue until the user responds. This is a hard gate — the `AskUserQuestion` tool triggers platform notifications and status indicators so the user knows you need @@ -98,6 +91,12 @@ After presenting results, consider what just happened, then offer options that m - A trivial fix might go straight from `/fix` → `/test` → `/review` → `/pr` - If the user already has their own PR process, they may stop after `/review` +**Always recommend `/review` before `/pr`.** Do not recommend skipping review, even for +fixes that seem simple or mechanical. You implemented the fix and wrote the +tests — you are not in a position to objectively evaluate their quality. +Review exists precisely to catch what the fixer misses. Only the user can +decide to skip it. + ### How to Present Options Lead with your top recommendation, then list alternatives briefly: @@ -126,10 +125,6 @@ directly — don't force them through earlier phases. response between phases. This is the single most important rule in this controller. If you proceed to another phase without the user's explicit go-ahead, the workflow is broken. -- **Always read skill files.** Every phase execution MUST begin with a Read - tool call on the skill's `SKILL.md` file. Do not execute a phase from memory - or general knowledge — the skill files contain specific, tested instructions - that differ from what you might do ad-hoc. - **Urgency does not bypass process.** Security advisories, critical bugs, and production incidents may create pressure to act fast. The phase-gated workflow exists precisely to prevent hasty action. Follow every phase gate diff --git a/workflows/bugfix/.claude/skills/diagnose/SKILL.md b/workflows/bugfix/.claude/skills/diagnose/SKILL.md index 02003d10..b11a3c54 100755 --- a/workflows/bugfix/.claude/skills/diagnose/SKILL.md +++ b/workflows/bugfix/.claude/skills/diagnose/SKILL.md @@ -5,14 +5,6 @@ description: Perform systematic root cause analysis to identify the underlying i # Diagnose Root Cause Skill -## Dispatch - -If you were dispatched by the controller or by speedrun, continue below. -Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send -you back here with the proper workflow context. - ---- - You are a systematic root cause analysis specialist. Your mission is to identify the underlying issue causing a bug by understanding *why* it occurs, not just *what* is happening. ## Your Role @@ -125,5 +117,3 @@ Report your findings: - The identified root cause (or top hypotheses if uncertain) - Confidence level in the diagnosis - 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/skills/speedrun/SKILL.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 09cb3e4c..b4cecff5 100644 --- a/workflows/bugfix/.claude/skills/document/SKILL.md +++ b/workflows/bugfix/.claude/skills/document/SKILL.md @@ -5,14 +5,6 @@ description: Create comprehensive documentation for a bug fix including issue up # Document Fix Skill -## Dispatch - -If you were dispatched by the controller or by speedrun, continue below. -Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send -you back here with the proper workflow context. - ---- - You are a thorough documentation specialist for bug fixes. Your mission is to create comprehensive documentation that ensures the fix is properly communicated, tracked, and accessible to all stakeholders. ## Your Role @@ -172,5 +164,3 @@ Report your results: - What documents were created and where - Any gaps flagged for later - -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.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 bb09c684..7d7ce190 100755 --- a/workflows/bugfix/.claude/skills/fix/SKILL.md +++ b/workflows/bugfix/.claude/skills/fix/SKILL.md @@ -5,14 +5,6 @@ description: Implement a bug fix based on root cause analysis, following project # Implement Bug Fix Skill -## Dispatch - -If you were dispatched by the controller or by speedrun, continue below. -Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send -you back here with the proper workflow context. - ---- - You are a disciplined bug fix implementation specialist. Your mission is to implement minimal, correct, and maintainable fixes based on root cause analysis, following project best practices and coding standards. ## Your Role @@ -163,5 +155,3 @@ Report your results: - What was changed (files, approach) - What quality checks passed - 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/skills/speedrun/SKILL.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 a637a325..f5ec0351 100644 --- a/workflows/bugfix/.claude/skills/pr/SKILL.md +++ b/workflows/bugfix/.claude/skills/pr/SKILL.md @@ -692,5 +692,3 @@ Report your results: - What was included - Any follow-up actions needed (mark ready for review, add reviewers, etc.) -Then return to the coordinating skill that dispatched you (if any) 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 f8f7fe60..01fc609c 100644 --- a/workflows/bugfix/.claude/skills/reproduce/SKILL.md +++ b/workflows/bugfix/.claude/skills/reproduce/SKILL.md @@ -5,14 +5,6 @@ description: Systematically reproduce a reported bug and document its observable # Reproduce Bug Skill -## Dispatch - -If you were dispatched by the controller or by speedrun, continue below. -Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send -you back here with the proper workflow context. - ---- - You are a systematic bug reproduction specialist. Your mission is to confirm and document reported bugs, creating a solid foundation for diagnosis by establishing clear, reproducible test cases. ## Your Role @@ -153,5 +145,3 @@ Report your findings: - Whether the bug was successfully reproduced - Key observations and environment details - 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/skills/speedrun/SKILL.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 8fd72571..079a5bcb 100644 --- a/workflows/bugfix/.claude/skills/review/SKILL.md +++ b/workflows/bugfix/.claude/skills/review/SKILL.md @@ -5,14 +5,6 @@ description: Critically evaluate a bug fix and its tests, then recommend next st # Review Fix & Tests Skill -## Dispatch - -If you were dispatched by the controller or by speedrun, continue below. -Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send -you back here with the proper workflow context. - ---- - You are a skeptical reviewer whose job is to poke holes in the fix and its tests. Your goal is not to validate — it's to find what's wrong, what's missing, and what could fail in production. Be constructive but honest. @@ -206,5 +198,3 @@ in Step 5. ## When This Phase Is Done Your verdict and recommendation (from Step 5) serve as the phase summary. - -Then announce which file you are returning to (e.g., "Returning to `.claude/skills/controller/SKILL.md`." or "Returning to `.claude/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/.claude/skills/speedrun/SKILL.md b/workflows/bugfix/.claude/skills/speedrun/SKILL.md index a451be46..30bba5de 100644 --- a/workflows/bugfix/.claude/skills/speedrun/SKILL.md +++ b/workflows/bugfix/.claude/skills/speedrun/SKILL.md @@ -5,8 +5,8 @@ description: Speed-run the remaining bugfix phases without stopping between them # /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`). +You are in **speedrun mode**. Run the next incomplete phase, then continue to +the next one. Do not use the controller skill. ## User Input @@ -20,13 +20,12 @@ phases to include or skip. ## How Speedrun Works -Each time you read this file, you will: +The speedrun loop: 1. Determine which phase to run next (see "Determine Next Phase" below) 2. If all phases are done (including `/summary`), 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/skills/speedrun/SKILL.md`). Re-read it and repeat. +3. Otherwise, run the skill for that phase (see "Execute a Phase" below) +4. When the skill completes, continue to the next phase This loop continues until all phases are complete or an escalation stops you. @@ -39,15 +38,15 @@ context, then pick the first phase that is NOT done. | 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 | -| summary | `.claude/skills/summary/SKILL.md` | `artifacts/bugfix/summary.md` exists | +| assess | `assess` | `artifacts/bugfix/reports/assessment.md` exists | +| reproduce | `reproduce` | `artifacts/bugfix/reports/reproduction.md` exists | +| diagnose | `diagnose` | `artifacts/bugfix/analysis/root-cause.md` exists | +| fix | `fix` | `artifacts/bugfix/fixes/implementation-notes.md` exists | +| test | `test` | `artifacts/bugfix/tests/verification.md` exists | +| review | `review` | `artifacts/bugfix/review/verdict.md` exists | +| document | `document` | `artifacts/bugfix/docs/pr-description.md` exists | +| pr | `pr` | A PR URL has been shared in conversation | +| summary | `summary` | `artifacts/bugfix/summary.md` exists | ### Rules @@ -59,25 +58,21 @@ context, then pick the first phase that is NOT done. ## Execute a Phase -1. **Announce** the phase and include this file as the dispatcher: - "Starting the /[phase] phase (dispatched by `.claude/skills/speedrun/SKILL.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/skills/speedrun/SKILL.md`). +1. **Announce** the phase to the user (e.g., "Starting the /fix phase — speedrun mode.") +2. **Run** the skill for the current phase +3. When the skill completes, continue to the next phase ## Speedrun Rules -- **Do not stop and wait between phases.** After each phase, return here and +- **Do not stop and wait between phases.** After each phase completes, continue to the next one. -- **Do not read the controller.** This skill replaces the controller for this - run. If you are tempted to read `.claude/skills/controller/SKILL.md`, read - `.claude/skills/speedrun/SKILL.md` instead. +- **Do not use the controller skill.** This skill replaces the controller for + this run. - **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. + After the user responds, continue with the next phase. ## Phase-Specific Notes diff --git a/workflows/bugfix/.claude/skills/summary/SKILL.md b/workflows/bugfix/.claude/skills/summary/SKILL.md index b2b67574..55fa8934 100644 --- a/workflows/bugfix/.claude/skills/summary/SKILL.md +++ b/workflows/bugfix/.claude/skills/summary/SKILL.md @@ -5,11 +5,8 @@ description: Scan all workflow artifacts and present a synthesized summary of fi # Workflow Summary Skill -## Dispatch - -This skill can be invoked at any point in the workflow — from the controller, -from speedrun, or directly by the user. It does not require prior phases to -have completed; it summarizes whatever exists so far. +This skill can be invoked at any point in the workflow. It does not require +prior phases to have completed; it summarizes whatever exists so far. --- @@ -136,6 +133,3 @@ Save the summary to `artifacts/bugfix/summary.md`. The summary is the deliverable. Present it and stop — there is no next phase to recommend. - -If dispatched by the controller or speedrun, announce which file you are -returning to and re-read it. diff --git a/workflows/bugfix/.claude/skills/test/SKILL.md b/workflows/bugfix/.claude/skills/test/SKILL.md index 46ffac8d..1c4f2185 100755 --- a/workflows/bugfix/.claude/skills/test/SKILL.md +++ b/workflows/bugfix/.claude/skills/test/SKILL.md @@ -5,14 +5,6 @@ description: Verify a bug fix with comprehensive testing and create regression t # Test & Verify Fix Skill -## Dispatch - -If you were dispatched by the controller or by speedrun, continue below. -Otherwise, read `.claude/skills/controller/SKILL.md` first — it will send -you back here with the proper workflow context. - ---- - You are a thorough testing and verification specialist. Your mission is to verify that a bug fix works correctly and create comprehensive tests to prevent regression, ensuring the fix resolves the issue without introducing new problems. ## Your Role @@ -247,5 +239,3 @@ Report your results: - How many tests were added and their results - Whether the full test suite passes - 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/skills/speedrun/SKILL.md` for next phase.") and **re-read that file** for next-step guidance. diff --git a/workflows/bugfix/CLAUDE.md b/workflows/bugfix/CLAUDE.md index 9a55676c..b9e4ce69 100755 --- a/workflows/bugfix/CLAUDE.md +++ b/workflows/bugfix/CLAUDE.md @@ -12,11 +12,9 @@ Systematic bug resolution through these phases: 8. **PR** (`/pr`) — Submit a pull request 9. **Summary** (`/summary`) — Synthesize all artifacts into a final status report -All phases are implemented as skills at `.claude/skills/{name}/SKILL.md`. -The workflow controller at `.claude/skills/controller/SKILL.md` manages phase -transitions and recommendations. The `/speedrun` skill at -`.claude/skills/speedrun/SKILL.md` runs all remaining phases without stopping. -Artifacts go in `artifacts/bugfix/`. +All phases are implemented as skills. The controller skill manages phase +transitions and recommendations. The speedrun skill runs all remaining phases +without stopping. Artifacts go in `artifacts/bugfix/`. ## Principles