| name | fix |
| description | Systematic diagnosis and repair of bugs, failures, and regressions — structured triage before action, with two walk-throughs (issues + fixes). Supports goal-based modes: General (standard investigate-fix-verify), TDD (test-first discipline), Hotfix (abbreviated emergency), Custom (user-defined lens). Triggers: "fix this", "fix the tests", "investigate this failure", "why is this broken", "something isn't working right", "performance is degraded". |
| version | 3 |
| tier | protocol |
Systematic diagnosis and repair of bugs, failures, and regressions — structured triage before action, with two walk-throughs (issues + fixes).
Fix Protocol (The Fixer's Code)
Execute §CMD_EXECUTE_SKILL_PHASES.
Session Parameters
{
"taskType": "FIX",
"phases": [
{"label": "0", "name": "Setup",
"steps": ["§CMD_REPORT_INTENT", "§CMD_PARSE_PARAMETERS", "§CMD_SELECT_MODE", "§CMD_INGEST_CONTEXT_BEFORE_WORK"],
"commands": [],
"proof": ["mode", "sessionDir", "parametersParsed"], "gate": false},
{"label": "1", "name": "Investigation",
"steps": ["§CMD_REPORT_INTENT", "§CMD_INTERROGATE"],
"commands": ["§CMD_ASK_ROUND", "§CMD_LOG_INTERACTION", "§CMD_APPEND_LOG"],
"proof": ["depthChosen", "roundsCompleted"]},
{"label": "2", "name": "Triage Walk-Through",
"steps": ["§CMD_REPORT_INTENT", "§CMD_GENERATE_PLAN", "§CMD_WALK_THROUGH_RESULTS"],
"commands": ["§CMD_LINK_FILE"],
"proof": ["planWritten", "issuesTriaged", "userApproved"]},
{"label": "3", "name": "Execution",
"steps": ["§CMD_SET_TICKET_IN_PROGRESS", "§CMD_SELECT_EXECUTION_PATH"],
"commands": [],
"proof": ["pathChosen", "pathsAvailable"], "gate": false},
{"label": "3.A", "name": "Fix Loop",
"steps": ["§CMD_REPORT_INTENT"],
"commands": ["§CMD_APPEND_LOG", "§CMD_TRACK_PROGRESS", "§CMD_ASK_USER_IF_STUCK"],
"proof": ["fixesApplied", "testsPass", "logEntries", "unresolvedBlocks"]},
{"label": "3.B", "name": "Agent Handoff",
"steps": ["§CMD_HANDOFF_TO_AGENT"], "commands": [], "proof": []},
{"label": "3.C", "name": "Parallel Agent Handoff",
"steps": ["§CMD_PARALLEL_HANDOFF"], "commands": [], "proof": []},
{"label": "4", "name": "Results Walk-Through",
"steps": ["§CMD_REPORT_INTENT", "§CMD_WALK_THROUGH_RESULTS"], "commands": [], "proof": ["resultsPresented", "userApproved"]},
{"label": "5", "name": "Synthesis",
"steps": ["§CMD_REPORT_INTENT", "§CMD_RUN_SYNTHESIS_PIPELINE"], "commands": [], "proof": [], "gate": false},
{"label": "5.1", "name": "Checklists",
"steps": ["§CMD_VALIDATE_ARTIFACTS", "§CMD_RESOLVE_BARE_TAGS", "§CMD_PROCESS_CHECKLISTS"], "commands": [], "proof": [], "gate": false},
{"label": "5.2", "name": "Debrief",
"steps": ["§CMD_GENERATE_DEBRIEF"], "commands": [], "proof": ["debriefFile", "debriefTags"], "gate": false},
{"label": "5.3", "name": "Pipeline",
"steps": ["§CMD_MANAGE_DIRECTIVES", "§CMD_PROCESS_DELEGATIONS", "§CMD_DISPATCH_APPROVAL", "§CMD_CAPTURE_SIDE_DISCOVERIES", "§CMD_RESOLVE_CROSS_SESSION_TAGS", "§CMD_MANAGE_BACKLINKS", "§CMD_MANAGE_ALERTS", "§CMD_REPORT_LEFTOVER_WORK"], "commands": [], "proof": [], "gate": false},
{"label": "5.4", "name": "Close",
"steps": ["§CMD_REPORT_ARTIFACTS", "§CMD_REPORT_SUMMARY", "§CMD_SURFACE_OPPORTUNITIES", "§CMD_OFFER_COUNCIL_REVIEW", "§CMD_OFFER_GRAPH_VIZ", "§CMD_CLOSE_SESSION", "§CMD_PRESENT_NEXT_STEPS"], "commands": [], "proof": ["reviewOffered", "decision", "graphOffered"], "gate": false}
],
"nextSkills": ["/test", "/prove", "/implement", "/analyze", "/document", "/chores"],
"directives": ["TESTING.md", "PITFALLS.md", "CONTRIBUTING.md", "CHECKLIST.md"],
"planTemplate": "assets/TEMPLATE_FIX_PLAN.md",
"logTemplate": "assets/TEMPLATE_FIX_LOG.md",
"debriefTemplate": "assets/TEMPLATE_FIX.md",
"requestTemplate": "assets/TEMPLATE_FIX_REQUEST.md",
"responseTemplate": "assets/TEMPLATE_FIX_RESPONSE.md",
"modes": {
"general": {"label": "General", "description": "Standard investigate-fix-verify", "file": "modes/general.md"},
"tdd": {"label": "TDD", "description": "Test-first discipline", "file": "modes/tdd.md"},
"hotfix": {"label": "Hotfix", "description": "Emergency abbreviated", "file": "modes/hotfix.md"},
"custom": {"label": "Custom", "description": "User-defined lens", "file": "modes/custom.md"}
}
}
0. Setup
§CMD_REPORT_INTENT:
0: Fixing ___. Symptoms: ___. Trigger: ___.
Focus: ___.
Not: ___.
§CMD_EXECUTE_PHASE_STEPS(0.0.*)
- Scope: Understand the [Problem] and [Symptoms].
Mode Selection (§CMD_SELECT_MODE):
On selection: Read the corresponding modes/{mode}.md file. It defines Role, Goal, Mindset, and Configuration.
On "Custom": Read ALL 3 named mode files first (modes/general.md, modes/tdd.md, modes/hotfix.md) for context, then read modes/custom.md. The user types their framing. Parse it into role/goal/mindset.
Record: Store the selected mode. It configures:
- Phase 0 role (from mode file)
- Phase 1 investigation topics (from mode file)
- Phase 2 & 4 walk-through configs (from mode file)
Initial Evidence: Capture initial state relevant to the fix mode:
- General: Reproduce the issue, document symptoms.
- TDD: Run the failing tests, capture output.
- Hotfix: Capture current system state and impact.
- Custom: Gather context relevant to the user's defined focus.
1. Investigation
§CMD_REPORT_INTENT:
1: Interrogating ___ assumptions before triaging fixes. ___.
Focus: ___.
Not: ___.
§CMD_EXECUTE_PHASE_STEPS(1.0.*)
Investigation Topics (Fix)
Primary topic source: the Triage Topics from the loaded mode file (modes/{mode}.md). Use mode-specific topics as the primary investigation lens.
The standard topics below are available for ALL modes as supplementary investigation themes. Adapt to the task -- skip irrelevant ones, invent new ones as needed.
Standard topics (typically covered once, available in all modes):
- Symptom characterization -- exact error messages, stack traces, failure frequency
- Reproduction steps -- minimal repro, environment specifics, intermittent vs consistent
- Environment & versions -- Node version, dependency changes, OS differences, CI vs local
- Recent changes -- what changed recently, git blame suspects, deployment timeline
- Blast radius -- how many tests/features are affected, is this isolated or systemic
- Logs & observability -- relevant log output, monitoring data, debug traces available
- Hypotheses -- initial theories about root cause, rank by likelihood
- Isolation strategy -- how to narrow down the cause, bisection approach
- Similar past bugs -- has this pattern been seen before, related incidents
- Rollback options -- can we revert, what's the blast radius of rollback
Nuanced Triage Criteria
- Tier 1: High-Confidence Fixes (The "Obvious")
- Setup Noise: Missing mocks, syntax errors, obvious import path mismatches after a refactor.
- Simple API Aliases: A method was renamed and the logic is identical.
- Configuration Drift: Environment variables, feature flags, or config values that are stale or mismatched.
- Known Patterns: Issues matching a well-documented pattern with a known fix.
- Tier 2: Investigations (The "Mysterious")
- API Erosion: A method is missing, and it's unclear if it was moved, deleted, or subsumed.
- Logic Drift: Expected behavior
A, but observed behavior B. Check if expectations are outdated or if this is a regression.
- Intermittent Failures: Issues that appear under specific conditions.
- Silent Failures: The system appears to work but logs internal errors.
- Cross-Layer Issues: The symptom appears in one layer but the root cause is in another.
Rules of Thumb (The Fixer's Intuition)
- Don't Guess: If you can't find the root cause in 2 targeted searches, it's Tier 2. Park it.
- Context First: If the issue references documentation, specs, or config, you MUST read those sources before attempting a fix.
- Critique the Docs: If documentation contradicts code or is too vague, log a Documentation Insight/Critique entry immediately.
- No "Hack-Fixes": Do not mask symptoms with workarounds without understanding why the issue occurred.
- The "Dog vs. Tail" Rule: If a fix requires changing 5+ files to resolve one symptom, stop and ask for confirmation.
- Batch & Conquer: Look for "Failure Clusters" (multiple symptoms sharing the same root cause). Investigate the cluster as a unit.
- Follow the Data: Let metrics and logs guide hypotheses -- don't rely on code reading alone.
2. Triage Walk-Through
User reviews and approves what to fix before any code changes.
§CMD_REPORT_INTENT:
2: Presenting ___ investigated issues for triage. ___.
Focus: ___.
Not: ___.
§CMD_EXECUTE_PHASE_STEPS(2.0.*)
Plan structure (for FIX_PLAN.md):
- Phase 1: Easy Fixes (Tier 1).
- Phase 2: Bulk Investigations (Tier 2).
- Phase 3: User Confirmation of Options.
- Phase 4: Final Execution.
Walk-through (from loaded mode file):
§CMD_WALK_THROUGH_RESULTS Configuration:
mode: "plan"
gateQuestion: "Triage complete. Walk through the issues before fixing?"
debriefFile: "FIX_PLAN.md"
planQuestions:
- "Is this the right tier (Tier 1 vs Tier 2) for this issue?"
- "Should we fix this now, defer it, or investigate further?"
- "Any dependencies or risks I'm missing?"
If any items are flagged for revision, update the plan before proceeding.
3. Execution
Gateway: first flip an associated ticket to In Progress (§CMD_SET_TICKET_IN_PROGRESS — silent no-op when no ticket is attached), then select the execution path before entering a branch. The flip runs here, before the branch split, so every fix path is covered.
§CMD_REPORT_INTENT:
3: Selecting execution path for ___ fixes. ___.
Focus: ___.
Not: ___.
§CMD_EXECUTE_PHASE_STEPS(3.0.*)
3.A. Fix Loop
Execute repairs. Resolve Tier 1 first, then investigate Tier 2.
§CMD_REPORT_INTENT:
3.A: Executing ___-issue fix plan. Target: ___.
Focus: ___.
Not: ___.
§CMD_EXECUTE_PHASE_STEPS(3.A.*)
Keep the plan live (¶INV_KEEP_PLAN_LIVE): when the fix work deviates from the plan mid-loop — a new root cause, a re-tiered issue, a superseded repair — proactively append a dated ## 🔄 STATUS RECONCILIATION (YYYY-MM-DD) section (preserving the original plan; surgical checkbox edits only) and offer to log the course change to the ticket via /snapshot (skip-the-commit mode: description touch + a comment through §CMD_POST_TICKET_COMMENT). A stale plan misleads the next session and loses the decision trail.
Sub-Phase: Quick Wins (Tier 1)
- Action: Apply Tier 1 fixes.
- Verify: Run relevant verification (tests, reproduction steps, metrics).
- Log: Update
FIX_LOG.md.
- Park: If a fix isn't straightforward, move it to Tier 2.
Sub-Phase: Bulk Investigation (Tier 2)
- Strategy: Group related issues (Failure Clusters -- multiple symptoms sharing root cause).
- Doc Check: Read any documents referenced in the issue.
- Action: Identify root causes for parked issues.
Sub-Phase: User Confirmation (The Decision Point)
- Action: Present a report with Options for each investigated item.
- Choose: Execute
AskUserQuestion (multiSelect: false) for each item:
"Choose path for [item]:"
- "Fix Code" -- The implementation has a bug, fix it
- "Fix Test" -- The test expectations are wrong, update them
- "Workaround" -- Apply a temporary mitigation with documented tech debt
- "Further Investigation" -- Not enough info, dig deeper
Sub-Phase: Final Execution
- Action: Apply the chosen options.
- Verify: Confirm resolution per the fix mode's success criteria.
- Loop: If new issues arise or results are unclear, return to User Confirmation.
Rules of Engagement
- Don't Wage War: Do not fix issues "at all costs". If it looks like "the tail wagging the dog", stop and ask.
- Token Thrift: Group file reads and explorations. Don't investigate issue-by-issue if they share context.
- Stop the Bleeding: If you spend >15 mins on one issue without a discovery, park it.
- Document Everything: Every hypothesis, every dead end, every decision. The log is more valuable than the fix.
3.B. Agent Handoff
Hand off to a single autonomous agent.
§CMD_EXECUTE_PHASE_STEPS(3.B.*)
§CMD_HANDOFF_TO_AGENT with:
{
"agentName": "debugger",
"startAtPhase": "3.A: Fix Loop",
"planOrDirective": "[sessionDir]/FIX_PLAN.md",
"logFile": "FIX_LOG.md",
"taskSummary": "Fix: [brief description from taskSummary]"
}
3.C. Parallel Agent Handoff
Hand off to multiple agents working in parallel on independent plan chunks.
§CMD_EXECUTE_PHASE_STEPS(3.C.*)
§CMD_PARALLEL_HANDOFF with:
{
"agentName": "debugger",
"planFile": "[sessionDir]/FIX_PLAN.md",
"logFile": "FIX_LOG.md",
"taskSummary": "Fix: [brief description from taskSummary]"
}
4. Results Walk-Through
User reviews all applied fixes before synthesis.
§CMD_REPORT_INTENT:
4: Presenting ___ applied fixes for review. ___.
Focus: ___.
Not: ___.
§CMD_EXECUTE_PHASE_STEPS(4.0.*)
Walk-through (from loaded mode file):
§CMD_WALK_THROUGH_RESULTS Configuration:
mode: "results"
gateQuestion: "Fixes applied. Walk through the changes?"
debriefFile: "FIX_LOG.md"
5. Synthesis
When all fixes are applied and verified.
§CMD_REPORT_INTENT:
5: Synthesizing. ___ fixes applied, ___ tests passing.
Focus: ___.
Not: ___.
§CMD_EXECUTE_PHASE_STEPS(5.0.*)
Debrief notes (for FIX.md):
- The Story: Narrate the diagnostic journey.
- Deviation Analysis: Compare Plan vs. Reality -- where did we pivot?
- Root Cause Analysis: Document the actual root causes found.
- War Story: The hardest moment of the investigation.
- Tech Debt: What shortcuts did we take or discover?
- System Health: What did we learn about the system's overall health?
- Parking Lot: What was parked or deferred.
- Expert Opinion: Your unfiltered assessment.
Walk-through config:
§CMD_WALK_THROUGH_RESULTS Configuration:
mode: "results"
gateQuestion: "Fixes complete. Walk through the changes?"
debriefFile: "FIX.md"
Before closing, offer a /council panel review on the fix session <dir> via §CMD_OFFER_COUNCIL_REVIEW (offer, not force) -- diverse expert eyes on the fix and its blast radius. Then offer a /graph flowgraph of the failure-path / control-flow of the bug via §CMD_OFFER_GRAPH_VIZ (offer, context-gated -- skips linear artifacts).
