Help us improve
Share bugs, ideas, or general feedback.
npx claudepluginhub xoai/sage --plugin sageHow this skill is triggered — by the user, by Claude, or both
Slash command
/sage:fixThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
- PERSONA: Read sage/core/agents/debugger.persona.md for your mindset.
Root cause based one-shot bug fix. Runs a full investigation pipeline: debugger diagnosis, gap analysis, requirements generation, execution, and verification. Includes QA suggestions after successful fix.
Executes systematic debugging loop: reproduce bug, analyze root cause, apply fix, verify with independent agent challenge to confirm fundamental resolution over workarounds.
Share bugs, ideas, or general feedback.
Diagnose, then scope, then fix. Never skip steps.
Scan .sage/work/ for fix-related directories with status: in-progress.
This scan is MANDATORY — check the DISK.
Manifest-first path: If manifest.md exists for a fix cycle, read it. Resume at the phase indicated.
Fallback path: If no manifest but artifacts exist:
If not found: start new investigation at Step 1.
Read .sage/decisions.md for context — previous root cause analyses
and fix patterns may be relevant.
Surgical fixes: No manifest. Too fast — completes in one session. Moderate fixes: Create manifest when fix plan is written (Step 3). Systemic fixes: Create manifest at escalation point. Update at fix scope gate and close checkpoint. Session end ([N]): Mandatory update for Moderate+ fixes.
Upstream report check (before asking the user):
Scan for recent reports that can serve as pre-diagnosed input:
.sage/work/*/ or .sage/docs/.sage/work/*/ or .sage/docs/If qa-report.md exists with bugs:
Sage: Found QA report with {N} bugs:
[1] BUG-1: {title} — {severity} — suggested: {Surgical/Moderate/Systemic}
[2] BUG-2: {title} — {severity} — suggested: {classification}
[3] BUG-3: {title} — {severity} — suggested: {classification}
[A] Fix all — accept classifications and proceed
[R] Reclassify — I want to change some classifications
Pick 1-N/A/R, or tell me what to fix.
On selection: skip Steps 1-2 (root cause already diagnosed in QA report). Use the QA report's reproduction steps and evidence. Proceed to Step 3 (scope the fix) with the QA bug's suggested classification.
If design-review.md exists with mechanical findings:
Sage: Found design review with {N} mechanical findings:
[1] {finding} — {severity} — /fix (mechanical)
[2] {finding} — {severity} — /fix (mechanical)
[M] Also found {K} design-decision findings (manual — not fixable by agent)
[A] Fix mechanical findings — accept and proceed
Pick 1-N/A, or tell me what to fix.
Design-decision findings are EXCLUDED from the fix pipeline. Show them as a summary ("manual action needed: {K} findings") but do NOT attempt to fix them. These require human judgment.
If both reports exist: Present QA bugs first (functional issues), then design mechanical findings. User can choose to fix all or select.
If no reports exist: Proceed with standard fix flow below.
Ask for or identify: what's broken, when it started, error messages, steps to reproduce. If the user already provided details, confirm your understanding before proceeding.
If the problem description is vague (no error message, no steps to reproduce, no specific behavior described), ask for specifics before investigating. Don't guess — misdiagnosis from vague reports wastes more time than one clarifying question.
Sage: Here's what I understand:
[C] Correct — start debugging | Or clarify what I got wrong
NO FIXES BEFORE THIS STEP COMPLETES. Read the relevant code. Trace the error. Gather evidence. The goal is UNDERSTANDING, not a fix.
For systematic debugging methodology, read
sage/core/capabilities/debugging/systematic-debug/SKILL.md.
Track investigation approaches. When changing hypothesis or investigation direction, log it:
Append to .sage/work/[fix-initiative]/scratch.md:
approach-[N]: [hypothesis tried] — [what the evidence showed]
If scratch.md has 3+ approaches, this is a gotcha trigger — store
the finding via self-learning with WHEN/CHECK/BECAUSE format.
Produce a root cause statement with evidence:
Sage: Root cause identified.
Cause: [what's actually wrong — the source, not the symptom] Evidence: [what you observed that confirms this] Chain: [how the root cause leads to the visible symptom] Confidence: [high / medium / low]
If multiple potential causes exist:
Sage: I found two possible causes:
[1] [Cause A] — in [file:line] — [evidence for this] [2] [Cause B] — in [file:line] — [evidence for this]
Which should I investigate first?
Red flags — STOP and return to investigation if you catch yourself thinking:
If stuck after 3+ attempts: Activate the problem-solving skill.
🔒 ROOT CAUSE GATE: Sage: Root cause analysis complete.
Cause: [root cause statement] Evidence: [what confirms it] Confidence: [high/medium/low]
[A] Approve diagnosis — continue to fix scoping [R] Revise — investigate further [S] Stuck — try a different approach (activates problem-solving) [N] New session — type /fix to continue
Pick A/R/E/N, or tell me what to change.
Pick A/R/S/N, or tell me what to change.
Do not proceed to Step 3 until the user confirms the root cause.
AFTER root cause is confirmed, BEFORE writing any fix code.
Classify the fix by structural impact:
Surgical: 1-2 files changed, no interface changes, no new abstractions. The fix is obvious from the root cause. → Proceed directly to Step 4 (implement fix).
Moderate: 3-5 files changed, OR test infrastructure changes,
OR error handling pattern changes. The fix is clear but touches
multiple components.
→ MUST write a fix plan before implementing:
Save to .sage/work/[fix-initiative]/plan.md:
Systemic: 5+ files changed, OR interface/API changes, OR new abstractions needed, OR architectural implications. This is no longer a fix — it's a redesign. → MUST escalate:
Sage: This fix is systemic — it requires [interface changes / new abstractions / architectural changes].
Root cause: [summary] Impact: [N files, M interfaces, architectural concern]
[1] Escalate to /build — write spec for the fix as a feature [2] Escalate to /architect — the root cause is architectural [3] Proceed as fix anyway — I accept the risk of a large unplanned change
If the user chooses [3], write a fix plan (same as Moderate) and record the decision in decisions.md.
Escalation signals (any ONE makes it Moderate or above):
Anti-downgrade: Do NOT classify as Surgical to skip the plan. If you find yourself thinking "I'll just quickly change these 5 files," that's Moderate. If you're thinking "the real problem is the architecture," that's Systemic. Trust the signals, not your optimism about how fast the fix will be.
🔒 FIX SCOPE GATE (Moderate+ only): Sage: Fix scope: [Moderate/Systemic]
Files: [list of files to change] Changes: [summary of what changes] Tests: [what tests to add/modify] Risk: [what could go wrong]
[A] Approve plan — start implementing [R] Revise — adjust the approach [E] Escalate — type /build or /architect instead [N] New session — type /fix to continue
Pick A/R/E/N, or tell me what to change.
Pick A/R/S/N, or tell me what to change.
Write a failing test that reproduces the bug. Confirm the test fails for the right reason (the root cause, not a setup issue). Fix the code. Verify the test passes.
For Moderate+ fixes: Follow the plan. Check off each file as you change it. Do NOT change files not in the plan — if you discover additional changes are needed, update the plan first.
Scope guard during fix: If the fix starts growing beyond the plan, STOP:
Sage: The fix is expanding beyond the plan. Originally: [N files, M changes] Now: [N+X files, M+Y changes]
[1] Update the plan and continue [2] Escalate to /build [3] Revert to original plan and accept limitations
Run the verification command. Read the output. THEN report.
For detailed verification process, read
sage/core/capabilities/debugging/verify-completion/SKILL.md.
Sage: Verification results:
Test suite: [command that was run] Result: [X passed, 0 failed] ← paste actual output Regression check: [any related tests that also pass]
If tests fail after the fix: Return to Step 2. The root cause analysis was incomplete — either the diagnosis was wrong, or the fix introduced a new issue.
Self-check before presenting (FILE CHECKS):
Sage: Fix verified.
[A] Approve — commit and close [R] Revise — something's not right [V] Verify — type /review for independent check
Pick A/R/V, or tell me what to change.
On approval — Post-Flight (Rule 7):
.sage/decisions.mdself-learning)
with WHEN/CHECK/BECAUSE prevention ruleNext steps: /reflect — review what went wrong, prevent recurrence /review — independent evaluation of the fix /build — spec → plan → implement (if fix revealed a feature need)
Type a command, or describe what you want to do next.
Communication style: Diagnostic precision. State root cause clearly, explain the chain of causation, describe the fix scope assessment, and verify with evidence.
Good fix output: