agentleFS
Alexander-TyagunovAlexander-Tyagunov/magician/skills/unravel/SKILL.md

unravel

Skill14 starsChanged 50 days agoMITView on GitHub

Hypothesis-first debugging; one change at a time, then a regression test. Use when a bug, error, regression, failing test, or outage is reported; not for features.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Hypothesis gate (AskUserQuestion): Put the hypothesis to the user via AskUserQuestion (never bare prose) — "Does this hypothesis match what …

    line 31
  2. Distinctive:

    Add targeted logging/assertions: if needed — not scattered throughout

    line 44
  3. Very specific:

    If the bug involves an unfamiliar error, library, or framework behavior, use /magic (context7 + web) to gather external evidence — known …

    line 49
  4. Distinctive:

    If refuted, mark it off and test the next

    line 54

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/unravel — Systematic Debugging

Bundled command: if kg is not found, run it as ${CLAUDE_PLUGIN_ROOT}/tools/kg and give subagents that full path. If that is missing too (Claude chat ships no plugin tools), skip the kg steps and search the code directly.

Debug systematically. No random changes in the hope something helps.

Scale /effort to bug complexity — for deep, multi-layer root-cause hunts use xhigh (max only as an opt-in for a frontier problem; it is session-only). See lore/models.md.

<HARD-GATE> State your hypothesis and evidence BEFORE reading any code or making any change. This prevents the most common AI debugging failure: making changes without understanding the cause. </HARD-GATE>

When to use

Trigger phrases: "I have a bug / it's broken / not working / crashing", an error, exception, or stack trace, a regression, a test failure, a production issue or outage when the app is deployed. The investigation is grounded with /magic and the knowledge graph (kg query / kg blast) for root-cause research. Not for new features (/conjure, /ward) or performance tuning (/accelerate).

Process

Phase 1: Hypothesis Preflight

  1. Describe the symptom — exact error message, stack trace, reproduction steps
  2. State what you believe is wrong — one sentence: "I believe X is failing because Y"
  3. State what evidence would confirm or refute it
  4. Hypothesis gate (AskUserQuestion). Put the hypothesis to the user via AskUserQuestion (never bare prose) — "Does this hypothesis match what you're seeing?":

    • Matches — investigate (default) — the hypothesis fits; proceed to Phase 2 and run Phases 2–4 autonomously.
    • Different theory — you have another explanation; share it and I'll re-state the hypothesis before touching anything.

    End your turn at the tool call. Do not read any code or make any change until the user picks or redirects. Treat a free-form "yes / matches / looks right" as Matches — investigate.

Autonomy — approve the plan, then run

Once the hypothesis is agreed at the Phase 1 gate, run Phases 2–4 autonomously: don't stop to ask the owner before reading code, grep, kg query/blast/neighbors, adding targeted logging, running the failing case, or running the test suite. This skill pre-approves reads and the kg lookups only; reproduction commands, test runs, and edits go through Claude Code's normal permission prompt unless the user runs in auto mode or approves them. Re-gate only on the real side effect — the commit (git add/commit/push, per Phase 4). This does not weaken the Phase 1 HARD-GATE. See lore/autonomy.md.

Phase 2: Evidence Gathering

  1. Read relevant code — only the code related to the hypothesis. If a knowledge-graph index exists, kg query "<symptom/error/symbol>" to jump straight to the relevant file:line (and kg neighbors/kg blast to see what interacts with it) instead of broad greps — then read just those ranges.
    • Read the error and stack trace in full first — before opening any file. The trace usually names the failing file:line and often the fix itself; the top frame shows where it blew up, but the first frame in your own code is usually the real culprit. Feed that symbol straight into kg query.
  2. Add targeted logging/assertions if needed — not scattered throughout
    • In a multi-component system (CI → build → sign, api → service → db), instrument each component boundary — log what enters and exits every hop — and run the reproduction once to locate exactly where the flow breaks before changing anything. Fix where it actually breaks, not the first place you suspect.
  3. Run the failing case — capture exact output
    • Reproduce it consistently before proposing a fix — pin down the exact steps or inputs that trigger it every time. A bug you can't reproduce on demand isn't understood yet, and a fix for it is a guess you can't verify.
    • For an intermittent or async bug, run the reproduction in the background with the Bash tool and read its output when you're notified it exits (or check it as it runs), so the failing event (a 5xx, a crash, a specific log line) is captured instead of tailed by hand.
    • If the bug involves an unfamiliar error, library, or framework behavior, use /magic (context7 + web) to gather external evidence — known issues, version-specific bugs, correct API usage — and fold it into the hypothesis ranking in Phase 3.

Phase 3: Hypothesis Testing

  1. Rank hypotheses by likelihood based on evidence (most likely first)
  2. Test the most likely hypothesis — make one change, observe result
  3. If refuted, mark it off and test the next

Phase 4: Fix and Verify

  1. Implement the fix for the confirmed root cause
    • Re-run the ORIGINAL failing symptom — the exact command or steps from Phase 1 — and confirm it no longer reproduces. A fix isn't done until the symptom you started with is re-run and gone; code changed is not the same as bug fixed. See lore/verification.md.
  2. Write a regression test that would have caught this bug
  3. Run full test suite — no new failures
  4. Commit with message explaining root cause: fix: <root cause>, not just symptom — in auto mode, confirm with the user before committing (the commit is a side effect).

Anti-Patterns (Never Do These)

  • Making 3 changes at once to "see what helps"
  • Reading the entire codebase before forming a hypothesis
  • Fixing the symptom without understanding the cause
  • Skipping the regression test

Obstacles

If this skill runs as a dispatched unit and hits something that blocks or degrades the work, do not wait for a human who is not there and do not silently ship a degraded result — return the Obstacles block from lore/obstacles.md (fields: STATUS, OBSTACLE, BLOCKER, SEVERITY, WORKAROUND, RECURRENCE, SCOPE, NEXT) to the caller alongside whatever you completed; interactively, say the same in prose.

Completion Signal

"Root cause confirmed: <explanation>. Fix applied and regression test added. Run /certify."

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.