# Sage Fix

> Root cause diagnosis with evidence, Reproducing test, Minimal patch

- Skill: `xoai/sage-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xoai/sage-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xoai/sage-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xoai (https://skillmd.com/u/xoai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xoai/sage-fix

---


## When to Use
Load this skill when the user runs `/sage-fix` or asks to fix something (the Sage fix workflow).

## Arguments
Hermes does NOT interpolate an in-body argument token. The user's arguments/flags arrive as a SEPARATE instruction line appended to this skill invocation. Wherever the steps below refer to "the user's arguments", use the text of that appended instruction line.

## Independent review (delegate_task)
When a step calls for an independent review, invoke `delegate_task` against the `sage-reviewer` skill. Hermes delegate_task has NO toolset-restriction parameter — read-only is prompt-enforced, and you MUST verify afterward that the reviewer made no edits (e.g. `git status` unchanged) before accepting its verdict.

RULES (apply to every step — non-negotiable):
- PERSONA: Read sage/core/agents/debugger.persona.md for your mindset.
- Announce: "Sage → fix workflow." before starting work
- MEMORY FIRST: Before investigating, search sage-memory with the bug
  domain or error message as query, filter_tags: ["self-learning"], limit: 5.
  Check for previous root causes, gotchas, and fixes in this area. MANDATORY.
- MUST complete root cause investigation before ANY fix attempt.
  Present root cause with evidence to user. Wait for [A] confirmation.
  Do NOT skip this gate for ANY reason — not for "obvious" bugs, not for
  "simple" fixes, not for Surgical scope. Every fix needs confirmed diagnosis.
- AFTER root cause confirmed: MUST scope the fix (Surgical/Moderate/Systemic)
  Even Surgical fixes: present scope to user before implementing.
  Moderate+ (3+ files): write fix plan BEFORE implementing.
  Systemic (5+ files, interface changes): ESCALATE to /build or /architect.
  "I know what to change" is NOT a plan file.
- [A] = REVIEW: When user picks [A] at root cause gate or fix plan gate,
  you MUST run auto-review sub-agent BEFORE proceeding. [S] = Skip review
  (approve without review). Present [A] Review / [S] Skip review.
  Low-quality fixes are expensive — independent review catches weak diagnoses
  and incomplete plans. If you proceed without showing findings after [A],
  you violated the process.
- Verify: PASTE actual test output before claiming done — no summaries
- Choices: present with [1] [2] [3] bracket notation
- Never use code blocks for interaction (checkpoints, options, status)
- If user corrects your approach, store as self-learning before continuing


# Fix Workflow

Diagnose, then scope, then fix. Never skip steps.

## Auto-Pickup

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, run
`python3 sage/runtime/tools/manifest.py resume` (plugin installs:
`python3 "${CLAUDE_PLUGIN_ROOT}/tools/manifest.py" resume`; no python3 →
read the manifest by hand). Resume at the phase the brief indicates; the
manifest body is judgment *context, not orders* (cycle-protocol.md
§ Resume authority order).

**Fallback path:** If no manifest but artifacts exist:
- Investigation in progress → resume at Step 2
- Root cause confirmed, no fix plan → resume at Step 3 (scope)
- Fix applied, not verified → resume at Step 5 (verify)

If not found: start new investigation at Step 1.

Read the initiative's decisions.md (fall back to the global
`.sage/decisions.md`) for context — previous root cause analyses
and fix patterns may be relevant.

**Shared cycle protocol:** decision-log targeting (Rule 7), gate_state
discipline, phase announcements, and the session-break contract are shared across
the delivery workflows — see `core/workflows/_shared/cycle-protocol.md`.

### Manifest Lifecycle (fix workflow)

**Surgical fixes:** No manifest. Too fast — completes in one session.
This is the Tier-1 escape hatch: with no manifest, the Claude Code spec-gate
hook treats the cycle as inactive and never blocks edits.
**Moderate fixes:** Create manifest when fix plan is written (Step 3), `tier: standard`.
**Systemic fixes:** Create manifest at escalation point, `tier: large`.
**Update** at fix scope gate and close checkpoint.
**Session end ([N]):** Mandatory update for Moderate+ fixes.

**gate_state (Moderate/Systemic fixes — the spec-gate hook reads it):**
- Manifest created (fix plan drafted) → `pre-spec`
- Fix plan approved `[A]` → `plan-approved`
- Implementing the fix → `building`
- Fix verified / gates pass → `gates-passed`
- Close checkpoint → `complete`

While `gate_state` is `pre-spec`, edits to source files are blocked — write and
get `[A]` approval on the fix plan first (Rule 3). Surgical fixes skip this
entirely by having no manifest.

## Phase Announcements

At each major phase transition, announce before doing any phase work:

```
Sage: Entering UNDERSTAND phase [cycle-id] — investigating root cause.
Sage: Entering PLAN phase [cycle-id] — scoping the fix.
Sage: Entering DELIVER phase [cycle-id] — implementing and verifying fix.
```

The cycle ID is the directory name under `.sage/work/` (e.g., `20260324-auth-bug`).
For Surgical fixes without a cycle directory, use the bug description as cycle ID.

## Step 1: Understand the Problem

**Upstream report check (before asking the user):**

Scan for recent reports that can serve as pre-diagnosed input:

1. **qa-report.md** in `.sage/work/*/` or `.sage/docs/`
2. **design-review.md** in `.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:
- [Problem summary]
- [Expected vs actual behavior]

[C] Correct — start debugging  |  Or clarify what I got wrong

## Step 2: Investigate Root Cause

**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 sage-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:**
- "Quick fix for now, investigate later"
- "Just try changing X and see if it works"
- "It's probably X, let me fix that"
- "Should work now" (without evidence)

**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] Review — sub-agent verifies diagnosis, then proceed
[S] Skip review — approve without independent review
[R] Revise — investigate further
[K] Stuck — try a different approach (activates problem-solving)
[N] New session — type /fix to continue

Pick A/S/R/K/N, or tell me what to change.

**On [A]:** Run auto-review (root cause review prompt) before
proceeding. This catches weak diagnoses — symptom-level fixes that
will break again. See `sage/core/capabilities/review/auto-review/SKILL.md`.

Do not proceed to Step 3 until the user confirms the root cause.

## Step 3: Scope the Fix

**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 follows directly from the confirmed root cause.
→ Present classification to user for confirmation, then proceed
  to Step 4 (implement fix). Even Surgical fixes require the user
  to see and confirm the scope before implementation begins.

**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`:
  - Files to change and what changes in each
  - Tests to add or modify
  - Rollback approach if fix doesn't work
  Present [A]/[R] → wait for approval.

**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.

**Branch setup (git projects):** after classification, before any
fix code, create the initiative branch per
`sage/core/capabilities/execution/git-discipline/SKILL.md` —
propose `fix/<slug>`, confirm with the user, record `branch:` in
the manifest. Moderate and Systemic fixes always branch. **Surgical
fixes branch by default too**; the user may skip with explicit
consent, recorded in the initiative decision log — "branch overhead
exceeds the fix" is the user's call, never the agent's. Not a git
repository → skip silently.

**Parallel-session note (`isolation: worktree`).** If
`isolation:` in `.sage/config.yaml` is `worktree` and this session is
in the main checkout (not a linked worktree), apply the **worktree
bounce** from git-discipline (offer `sage worktree <slug>` as a
guided menu) before branching in place. With `isolation: branch`
(default), ignore this — branch in place as below.

**Escalation signals** (any ONE makes it Moderate or above):
- Fix touches more than 2 files
- Fix changes a function signature or API contract
- Fix requires a new abstraction (new class, new module, new pattern)
- Fix changes error handling in a way other code depends on
- Fix requires database migration
- You realize "the real fix is to restructure X"

**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] Review — sub-agent reviews fix plan, then implement
[S] Skip review — approve without independent review
[R] Revise — adjust the approach
[E] Escalate — type /build or /architect instead
[N] New session — type /fix to continue

Pick A/S/R/E/N, or tell me what to change.

**On [A]:** Run auto-review (fix plan review prompt) before
implementing. See `sage/core/capabilities/review/auto-review/SKILL.md`.

## Step 4: Implement Fix

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.

**Subagent execution (Moderate+ only).** Resolve the mode as `/build` Step 6 does
— parse flags, then `resolve_execution_mode()`; never read the `subagents` flag
directly. Where it resolves to `subagent`, follow
`sage/core/workflows/sub-workflows/subagent-execution.workflow.md`: each planned
file-group becomes a ledger task with a fresh implementer and a fresh reviewer.
Where the platform cannot dispatch, announce the degradation, log it, record
`execution_mode: inline (subagents-unavailable)`, and continue inline.

**Surgical fixes (1-2 files) stay inline regardless of the flag.** Dispatching a
fresh context to change two lines, then a second fresh context to review those
two lines, costs more than it can possibly return — and the root cause was
already established and approved by a human in Step 2, which is where a fix's
real risk lives. The mode exists to isolate accumulating context across many
tasks. A surgical fix has no accumulation to isolate.

**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

## Step 5: Verify and Quality Gates

**Run the verification command. Read the output. THEN report.**

For detailed verification process, read
`sage/core/capabilities/debugging/verify-completion/SKILL.md`.

1. Run the project's test suite (full or relevant subset)
2. Read the actual output — don't summarize from memory
3. Confirm: zero failures, zero errors
4. If any test fails, diagnose and fix before proceeding —
   do NOT present the checkpoint with failing tests

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-learning trigger:** If you return to Step 2 more than once
(i.e., 2+ failed fix attempts), this is a MANDATORY `gotcha` trigger.
Before attempting the next fix, store what you learned via
sage_memory_store with `[LRN:gotcha]` title, `self-learning` tag,
and four-part content (what happened, why wrong, what's correct,
prevention rule). Do NOT wait until the fix succeeds — capture the
learning NOW so future sessions benefit even if this session fails.

**Quality gates:** After tests pass, run quality gates per
`sage/core/workflows/sub-workflows/quality-gates.workflow.md`.
Read `.sage/gates/gate-modes.yaml` for fix mode activation —
Gate 3 (code quality review) and Gate 8 (auto-QA) run as optional
gates to catch low-quality fixes before they ship. Findings are
advisory but surfaced to the user.

## Step 6: Close

**Self-check before presenting (FILE CHECKS):**
- [ ] Root cause was presented and approved by user (Step 2 gate)
- [ ] For Moderate+ fixes: plan.md exists in .sage/work/
- [ ] Test output is PASTED in this response (not summarized)
- [ ] Fix is contained to planned files (no scope creep)
If ANY fails → go back. Do NOT present the checkpoint.

Sage: Fix verified.
- Root cause: [what was wrong]
- Scope: [Surgical/Moderate/Systemic]
- Change: [what was changed, in which files]
- Tests: [X passed, 0 failed — from actual output]
Decision: [root cause + fix approach]. (prepend to the initiative's
decisions.md)

[A] Approve — commit and close; branch stays unmerged
[M] Merge to [default] — user-gated merge per git-discipline
[R] Revise — something's not right
[V] Verify — type /review for independent check

Pick A/M/R/V, or tell me what to change.

[M] is the ONLY merge path — [A] never merges. On [M], apply the
merge protocol from `sage/core/capabilities/execution/git-discipline/
SKILL.md` — preconditions, the merge, conflict handling, and the
deletion offer all live there; do not restate them here. Omit [M]
when not a git repository or no initiative branch exists.

**On approval — Post-Flight (Rule 7):**
1. Prepend root cause and fix to the initiative's decisions.md
   (cross-initiative decisions go to the global `.sage/decisions.md`)
2. Update artifact frontmatter if relevant
3. Store root cause and fix in memory (tagged `self-learning`)
   with WHEN/CHECK/BECAUSE prevention rule
4. **Wiring check:** Verify the fix is fully connected — if you changed
   an interface, check all callers. If you added error handling, verify
   the error path is wired end-to-end. Incomplete wiring is the #1
   cause of fixes that need re-fixing.
5. **Ontology update (if sage-memory available):** If the fix changed
   module dependencies or interfaces (e.g., a service now calls a
   different service, a dependency was added/removed), update ontology
   relations. Most Surgical fixes won't need this — only update when
   the codebase's structural relationships changed.
4. **Next steps (Zone 3):**

Next 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.

## Quality Criteria

**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:
- Root cause identified with evidence, not just symptoms addressed
- Fix scope classified honestly (not downgraded to skip the plan)
- A reproducing test exists before the fix is applied
- Verification output is pasted (not summarized)
- If the bug has related patterns elsewhere, those are flagged
- The fix is minimal — no unrelated refactoring mixed in

## Rules

- Root cause before fix (Step 2 gate). DO NOT fix before root cause
  is confirmed with evidence.
- Scope before implementing (Step 3). Classify impact honestly.
- For Moderate+ fixes: plan.md MUST EXIST before implementation.
  "I know what to change" is NOT a plan file.
- Tests before code (Base Principle 1). Write failing test first.
- Verify with evidence (Rule 5). PASTE actual test output.
- Capture corrections (Rule 6). Store as self-learning.
- Minimal change: fix the bug, don't refactor the neighborhood.
- If stuck, use problem-solving skill. Don't retry the same approach.
- If the fix reveals a systemic issue, ESCALATE. Do not scope-creep
  a fix into a rebuild. Offer /build or /architect.

## Failure Modes

- **Agent skips root cause investigation:** Red flags section catches
  this pattern. The ROOT CAUSE GATE blocks proceeding.
- **Agent underestimates fix scope:** Escalation signals list catches
  the most common patterns. Anti-downgrade language blocks "I'll just
  quickly change these 5 files."
- **Fix grows during implementation:** Scope guard in Step 4 detects
  when the fix expands beyond the plan and forces a decision.
- **Agent claims tests pass without running them:** Self-check
  requires PASTED output. No paste = checkpoint not ready.