Skip to content
Skills Library
Programming · Building & coding

fix-root

/fix-root

End-to-end bug fix workflow, root cause first. Asks whether the behavior ever worked — if so it is a regression and git bisect finds the culprit commit instead of a hypothesis contest. Otherwise triages into a short track or a full track (competing hypotheses as an anchoring-bias gate, graph evidence, a caller baseline re-verified after). Every track keeps a failing test before the fix, a minimal fix at the root cause only, and a full suite run. Use when the user asks to fix a bug, find or understand the root cause, corrige ce bug, debug this error, resolve this stack trace or exception, do a

Repository
skills ↗
Licence
MIT
Last repository change
12.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/bisect-run.sh, scripts/verify-test-first.sh

What it does and when to use it

End-to-end bug fix workflow, root cause first. Asks whether the behavior ever worked — if so it is a regression and git bisect finds the culprit commit instead of a hypothesis contest. Otherwise triages into a short track or a full track (competing hypotheses as an anchoring-bias gate, graph evidence, a caller baseline re-verified after). Every track keeps a failing test before the fix, a minimal fix at the root cause only, and a full suite run. Use when the user asks to fix a bug, find or understand the root cause, corrige ce bug, debug this error, resolve this stack trace or exception, do a

Original author description

End-to-end bug fix workflow, root cause first. Asks whether the behavior ever worked — if so it is a regression and git bisect finds the culprit commit instead of a hypothesis contest. Otherwise triages into a short track or a full track (competing hypotheses as an anchoring-bias gate, graph evidence, a caller baseline re-verified after). Every track keeps a failing test before the fix, a minimal fix at the root cause only, and a full suite run. Use when the user asks to fix a bug, find or understand the root cause, corrige ce bug, debug this error, resolve this stack trace or exception, do a

How it works

  1. Load only what this bug needs
  2. Triage — two questions before touching a tool
  3. Workflow
  4. Hard rules
Original SKILL.md headings · 138 lines, 1,054 words
SKILL.md preview
---
name: fix-root
description: End-to-end bug fix workflow, root cause first. Asks whether the
  behavior ever worked — if so it is a regression and git bisect finds the
  culprit commit instead of a hypothesis contest. Otherwise triages into a
  short track or a full track (competing hypotheses as an anchoring-bias
  gate, graph evidence, a caller baseline re-verified after). Every track
  keeps a failing test before the fix, a minimal fix at the root cause
  only, and a full suite run. Use when the user asks
  to fix a bug, find or understand the root cause, corrige ce bug, debug
  this error, resolve this stack trace or exception, do a root cause
  analysis, investigate why a call fails or returns an unexpected status,
  investiguer une erreur 403/4xx/5xx, analyse a bug ticket, comprendre
  pourquoi ça échoue, or reports a regression — it worked before, ça
  marchait avant, broken since the last deploy or release or migration,
  find the commit that broke it, git bisect — or invokes "/fix-root". Not
  for refactoring without a bug present.
---

# fix-root — root cause first, fix second, verify third

**Diagnose** (don't anchor on the first guess), **fix** (minimal, root
cause only), **verify** (prove the change did what the plan said). Each
part gates the next.

## Load only what this bug needs

This file is the whole short track. Read a reference only when its
condition holds — loading all four on a one-file bug is the waste this
skill exists to avoid.

| Read | When |
|:-----|:-----|
| `references/regression.md` | The behavior worked before — a tag, a release, a green CI run |
| `references/full-track.md` | The full track was triggered by the triage below |
| `references/graph-tools.md` | `codebase-memory-mcp` is available and you are about to call it |
| `references/test-first.md` | The red→green check misbehaves, or its script is missing |

MCP names are bare, not callable as written. Prefix `cbm_` under pi,
`mcp__codebase-memory-mcp__` under Claude Code. Under pi, `trace_path`,
`query_graph`, `detect_changes`, `get_architecture` and `get_graph_schema`
need one `cbm_search_tools` call first.

## Triage — two questions before touching a tool

**Is this a regression?** Did the behavior ever work — a release, a tag, a
commit, "it worked before the deploy", a test that used to pass? If yes,
history holds the answer: read `references/regression.md`, which replaces
steps 2-3 and nothing else. If nobody can name a moment when it worked, it
is not a regression — don't bisect a bug that was always there.

**Short or full track?** Short is the default. The full sequence is an
escalation, not the entry point: running it on a bug that didn't need it
burns the budget on ritual instead of on reading the faulty code, and
forces fabricated hypotheses — the very anchoring risk the gate exists to
prevent.

**Short track** — cause visible in the trace/diff/failing test, blast
radius ≤2 files, no concurrency, no service boundary crossed. Steps 1, 4,
7, 8, 10, 12 below. Nothing else.

**Full track** — escalate on any one of these, and only these:

- not reproducible on demand, or intermittent/timing-dependent
- crosses a service, process, or network boundary
- the cause is still not cited after 2 tool calls
- the fix would touch >2 files, a public signature, or shared mutable state
- a previous fix for the same symptom already failed

State the track in one line before the first tool call. Escalating
short → full mid-flight is expected, not a failure. The reverse never
happens: finishing early because it now looks simple is how a fix ships
unverified.

## Workflow

Steps marked *(full)* are skipped entirely on the short track.

### Diagnose

1. **Gather input.** Full error/stack trace (not just the first line),
   repro steps, expected vs actual. No repro steps → ask, or derive them
   from the trace; never guess a cause from a one-line summary. State the
   track here.
2. **Locate the blast site.** *(full)* Search for the symbols and error
   text named in the trace; reconnaissance only, no conclusion yet. Short
   track: the trace already names the site — read that file and go to 4.
   Regression: `references/regression.md` replaces this step.
3. **Generate ≥3 hypotheses before reading further code.** *(full, and
   skipped on the regression track — history already narrowed it)* Each
   from a different angle. Detail and the rejection discipline:
   `references/full-track.md`.
4. **Gather evidence.** Cite `file:line` or a qualified name for every
   claim — nothing is accepted or rejected without a cited source. Short
   track: one hypothesis and one citation, not zero. An uncited cause is a
   guess.
5. **Pick the root cause.** *(full)* State what evidence killed each
   rejected hypothesis.

### Fix

6. **Map the pre-fix baseline.** *(full)* Every caller and callee of the
   code about to change, plus the same faulty pattern elsewhere in the
   repo. This baseline is what step 9 verifies against, and it decides the
   edge cases the fix must cover. See `references/full-track.md`.
7. **Write the failing test first.** Reproduce the bug as a test, show it
   red, before touching the fix.
8. **Apply the minimal fix, root cause only.** No renames, no reshaping,
   no drive-by cleanup — note the temptation as a follow-up, not part of
   this diff. Then prove red→green mechanically rather than by self-report:

   ```bash
   <skill-dir>/scripts/verify-test-first.sh "<test-cmd>" -- <fix-file> [...]
   ```

   `<skill-dir>` is wherever this SKILL.md sits — resolve it from this
   file's own path, don't assume a repo layout. Exit 0 only on a confirmed
   red→green. Script missing, or a build cache making the replay lie:
   `references/test-first.md`.

### Verify

9. **Verify consequences against the plan.** *(full)* Real blast radius of
   the diff, post-fix callers compared to the step 6 baseline, sibling
   occurrences of the same bug, call-site compatibility if a signature
   changed. Checklist: `references/full-track.md`.
10. **Run the full suite**, not just the new test, plus one test per edge
    case from step 6. A failure that was already failing before the fix is
    a separate bug to report, not a reason to revert this one — check the
    pre-fix baseline or last known-green before blaming this change. A
    genuinely new failure means revert and re-diagnose, never patch
    forward on top of it.
11. **Self-critique, separate pass.** *(full)* Three ways this change could
    break something silently, each checked against the code rather than
    from memory. See `references/full-track.md`.
12. **Report.** Track chosen and why, root cause with its citation, the
    diff, tests added, suite status. Full track also: hypotheses rejected
    with their evidence, and the step 9 results.

## Hard rules

- The track is stated in one line before the first tool call. Escalating
  short → full is always allowed; full → short never.
- "It worked before" is checked before anything else. A regression
  diagnosed by hypothesis when a good ref existed is wasted budget.
- No cause is accepted without a cited `file:line` — either track. "Probably
  not that" is not a rejection.
- Full track: never fewer than 3 hypotheses. Short track: exactly one — if
  a second is needed to explain the evidence, that is the escalation
  signal, take it.
- Never skip the failing-test-first step. Both tracks, no exception.
- Never mix a refactor into this diff. Note it, don't do it here.
- Never report "done" without a full suite run — a fix that only passed its
  own new test is unverified. On the full track, step 9 is equally
  non-optional.
Files in this package (7)
  • SKILL.md 8 KB
  • references/full-track.md 4 KB
  • references/graph-tools.md 3 KB
  • references/regression.md 5 KB
  • references/test-first.md 3 KB
  • scripts/bisect-run.sh 7 KB
  • scripts/verify-test-first.sh 3 KB

Versions

The database has no other skills named fix-root.

Database snapshot: 13.11.2026 · package version ae43c622eef8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100hatch3r-bug-fix
    Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
  • 92debug
    Find the root cause of a bug before you fix it. Read this skill before you fix any bug. Read it also when the fix looks obvious. Use it when the user says "fix", "broken", "not working", "error", "failing", or "bug". Use it also when a test fails unexpectedly during other work.
  • 100m-debug
    Root-cause a bug or failing test: reproduce, competing hypotheses, regression test. Use for debug一下/为什么报错/这个测试挂了.
  • 100debug-detective
    Find the root cause of a bug, crash, error message or failing test, then fix it. Use when the user says "this is broken", "why does this fail", "I get this error", "the test is failing", "it worked yesterday", or pastes a stack trace.
  • 100bug-fix
    Bug-fixing workflow that coordinates diagnosis, test-driven reproduction, root-cause analysis, and targeted fixes. Use when the user wants to fix a bug with thorough investigation and regression testing.
  • 100debugging-expert
    Expert systematic debugging and root-cause analysis. Trigger keywords: debug, bug, error, exception, crash, stack trace, reproduce, root cause, works on my machine, intermittent, heisenbug, regression, git bisect, race condition. Use to diagnose failures methodically, find the…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.