bughunt-diagnose
Skill0 starsChanged 4 months agoMITView on GitHub
Phase 2 of 4 in the bughunt chain (repro → diagnose → fix → verify). Uses fairy-tales explore-role subagents to trace the root cause from the captured repro, then a review-role subagent to validate the hypothesis, producing a precise file:line root-cause finding. Trigger when the previous phase says "run bughunt-diagnose next", or standalone via "bughunt-diagnose", "phase 2 of bughunt", "diagnose the bug", "find the root cause".
In this repository21 other files it gives its agents.
- bughunt-fixSkill
- bughunt-reproSkill
- bughunt-verifySkill
- feature-ship-buildSkill
- feature-ship-reviewSkill
- feature-ship-shipSkill
- feature-ship-specSkill
- migrate-inventorySkill
- migrate-transformSkill
- migrate-verifySkill
- onboard-deepenSkill
- onboard-digestSkill
- onboard-mapSkill
- release-bumpSkill
- release-changelogSkill
- release-publishSkill
- release-tagSkill
- release-verifySkill
- research-artifactSkill
- research-gatherSkill
- research-synthesizeSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 4 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
All chain state is managed by the chain tool: authoritative JSON at .pi/fairy-tales/chains/bughunt/state.json with a human-readable …
- Very specific: line 34
Call the chain tool with action: "status", chain: "bughunt" (a legacy .bughunt-state.md from an older version is imported automatically):
- Very specific: line 37
If there is no run → abort: "No bughunt run found.
- Very specific: line 38
If the run is not active with currentPhase: "diagnose" → abort: "Expected the run to be at phase diagnose but it is at …
- Very specific: line 41
If the repro data (data.reproCommand / the repro phase summary) is missing → abort: "Phase pointer looks right but the Phase 1 output is …
- Very specific: line 44
If the tool reports the chain is locked by another session, abort.
- Very specific: line 67
If a returned quest is already done (crash-resume case), reuse its stored result.
- Distinctive: line 70
If the failure has multiple plausible starting points (e.g.
- Very specific: line 94
After extracting what's needed into chain state (Step 4), quest action consume each explore and review quest by id.
- Distinctive: line 99
Call the chain tool:
- Distinctive: line 118
After completing this phase, output exactly:
- Distinctive: line 123
Do not start the next phase.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Bughunt: Diagnose
Chain version: 2 (durable state contract — see docs/STATE-CONTRACT.md)
Phase 2 of 4: bughunt-repro → bughunt-diagnose → bughunt-fix → bughunt-verify
Overview
Traces the reproduced failure back to its root cause. Delegates the search to
fairy-tales explore role subagents so the codebase search happens in isolated
context instead of bloating this session, then delegates a skeptical second pass to a
fairy-tales review role subagent to pressure-test the hypothesis before it's
trusted. Output is a root-cause hypothesis plus a precise file:line location — not a
fix.
All chain state is managed by the chain tool: authoritative JSON at
.pi/fairy-tales/chains/bughunt/state.json with a human-readable state.md
projection beside it. Never create or edit state files by hand, and never create lock
files — the tool locks for you.
Load State
Call the chain tool with action: "status", chain: "bughunt" (a legacy
.bughunt-state.md from an older version is imported automatically):
- If there is no run → abort: "No bughunt run found. Run
bughunt-reprofirst." - If the run is not
activewithcurrentPhase: "diagnose"→ abort: "Expected the run to be at phasediagnosebut it is at<currentPhase/status>. Run that phase's skill instead." - If the repro data (
data.reproCommand/ the repro phase summary) is missing → abort: "Phase pointer looks right but the Phase 1 output is missing. Treat as corrupted — restart the chain or repair via chain action 'update'." - If the tool reports the chain is locked by another session, abort; a dead session's
lock can be cleared with
action: "unlock". Never create lock files yourself.
Note the run's runId — it keys this phase's quest dedupe keys.
Workflow
Step 1 — Fan out exploration via durable quests
Using the repro command, expected/actual behavior, error output, and environment
recorded in data from Phase 1, launch one or more fairy-tales explore role
subagents to trace the failure through the codebase. Because exploration can be
long-running and must survive a session restart, use the quest tool rather than a
bare agent call — one quest per exploration thread:
questactionenqueuewithrole: "explore", a self-contained task (the stack trace or symptom to trace, and what to report back — call path, the function/module where behavior diverges from expected, related code that could be involved), and:dedupeKey: "bughunt/<runId>/diagnose/<lead>"(a descriptive id for the lead being traced, e.g.primaryor a symptom name) — re-running a crashed phase returns the same quest instead of duplicating a search;chain: { chain: "bughunt", runId: "<runId>", phase: "diagnose" };retainUntilConsumed: true.
- If a returned quest is already
done(crash-resume case), reuse its stored result; otherwisequestactionrunwith itsidand collect the result.
If the failure has multiple plausible starting points (e.g. a symptom visible in two different call paths), enqueue several explore quests in parallel in a single batch rather than serially.
Step 2 — Validate with a review quest
Take the explore quests' findings and hand them to a fairy-tales review role
subagent via the quest tool: enqueue with role: "review", the repro details
and the candidate root cause, dedupeKey: "bughunt/<runId>/diagnose/review",
chain: { chain: "bughunt", runId: "<runId>", phase: "diagnose" }, and
retainUntilConsumed: true. Ask it to specifically check: does this location actually
explain the observed error output; are there alternate/competing explanations that fit
the symptoms just as well; is the proposed file:line the actual point of divergence
or just where the error surfaced (a stack trace's throw site is often downstream of
the real bug). Do not accept the first explore finding uncritically — the review pass
exists to catch tunnel vision. run the quest by id (or reuse its result if already
done).
Step 3 — Settle on the finding
Reconcile the explore and review output into one root-cause hypothesis with an exact
file:line. If the review quest rejects the hypothesis or surfaces a stronger
competing explanation, run another explore/review round on the new lead rather than
forcing a weak conclusion — diagnose does not hand off until the hypothesis holds up.
After extracting what's needed into chain state (Step 4), quest action consume
each explore and review quest by id.
Step 4 — Complete the phase
Call the chain tool:
action: "complete-phase", chain: "bughunt", phase: "diagnose",
summary: "root-cause hypothesis with precise location; <N> explore quests run; review quest confirmed / redirected the finding",
data: {
"rootCause": "<prose explanation of why the bug happens>",
"location": "<path/to/file>:<line>",
"exploreFindings": "<summary of what the explore quest(s) traced>",
"reviewConfirmation": "<summary of what the review quest checked and confirmed>"
},
artifacts: { "exploreQuests": "<quest ids>", "reviewQuest": "<quest id>" }The tool validates this is the current phase, advances the run to fix, and rewrites
the JSON + markdown projection atomically.
Handoff
After completing this phase, output exactly:
Phase 2 complete. Chain state updated (
.pi/fairy-tales/chains/bughunt/state.json). Run/bughunt-fixto begin Phase 3.
Do not start the next phase. Do not offer to continue. Output only the handoff line and stop.
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
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.

