bughunt-fix
Skill0 starsChanged 4 months agoMITView on GitHub
Phase 3 of 4 in the bughunt chain (repro → diagnose → fix → verify). Implements the fix with a fairy-tales build-role subagent at the diagnosed file:line; the post-edit `.pi/test-command` hook self-repairs failing tests automatically; checkpoints are taken before and after the edit so a bad fix can be rolled back. Trigger when the previous phase says "run bughunt-fix next", or standalone via "bughunt-fix", "phase 3 of bughunt", "implement the fix", "fix the bug".
In this repository21 other files it gives its agents.
- bughunt-diagnoseSkill
- 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
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 5 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
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 30
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 37
Call the chain tool with action: "status", chain: "bughunt" (a legacy .bughunt-state.md from an older version is imported automatically):
- Very specific: line 40
If there is no run → abort: "No bughunt run found.
- Very specific: line 41
If the run is not active with currentPhase: "fix" → abort: "Expected the run to be at phase fix but it is at <currentPhase/status>.
- Very specific: line 44
If the diagnosis data (data.rootCause / data.location or the diagnose phase summary) is missing → abort: "Phase pointer looks right but the …
- Very specific: line 47
If the tool reports the chain is locked by another session, abort.
- Distinctive: line 56
Before any edit, record the current baseline so a bad fix is trivially reversible: run git status --short (working tree should be clean or …
- Very specific: line 59
If the fairy-tales checkpoint extension has an existing checkpoint list, note the most recent one via /checkpoints as the fallback rollback …
- Very specific: line 76
If the returned quest is already done (crash-resume case), use its stored result directly.
- Distinctive: line 94
After the build-role quest's edit turn completes (and any self-repair loop settles), fairy-tales' checkpoint extension automatically …
- Distinctive: line 102
Call the chain tool:
- Distinctive: line 122
After completing this phase, output exactly:
- Distinctive: line 127
Do not start the next phase.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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: Fix
Chain version: 2 (durable state contract — see docs/STATE-CONTRACT.md)
Phase 3 of 4: bughunt-repro → bughunt-diagnose → bughunt-fix → bughunt-verify
Overview
Implements the fix at the location bughunt-diagnose found, using a fairy-tales
build role subagent so the edit happens with a tight, self-contained brief instead
of the accumulated diagnosis conversation. fairy-tales' post-edit hook
(.pi/test-command, if the project has one) runs automatically after the build-role
agent's edits land and steers any failures back to it to self-repair — this phase does
not need to invoke tests manually, but must report honestly if no .pi/test-command
exists (the self-repair loop silently doesn't run in that case). A checkpoint is
captured before the edit and confirmed after, so bughunt-verify (or the user) can
roll back cleanly if the fix turns out to be wrong.
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: "fix"→ abort: "Expected the run to be at phasefixbut it is at<currentPhase/status>. Run that phase's skill instead." - If the diagnosis data (
data.rootCause/data.locationor the diagnose phase summary) is missing → abort: "Phase pointer looks right but the Phase 2 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 key.
Workflow
Step 1 — Checkpoint before
Before any edit, record the current baseline so a bad fix is trivially reversible:
run git status --short (working tree should be clean or the pre-existing dirt
noted) and git rev-parse HEAD. Record this commit SHA as the before checkpoint.
If the fairy-tales checkpoint extension has an existing checkpoint list, note the
most recent one via /checkpoints as the fallback rollback point too.
Step 2 — Delegate the fix via a durable quest
Because the fix must survive a session restart, use the quest tool rather than a
bare agent call: enqueue with role: "build", a self-contained brief built from
chain state (the root-cause hypothesis and exact file:line from data.rootCause /
data.location, the repro command, and expected vs. actual behavior from Phase 1's
data), and:
dedupeKey: "bughunt/<runId>/fix/main"— if this phase crashed and is being re-run, the same quest (or its retained result) is returned instead of starting a duplicate fix attempt;chain: { chain: "bughunt", runId: "<runId>", phase: "fix" };retainUntilConsumed: true.
If the returned quest is already done (crash-resume case), use its stored result
directly. Otherwise quest action run with its id and collect the result.
Instruct it to make the minimal change that fixes the root cause — not a broader
refactor — and to avoid touching unrelated code. After extracting what's needed
(Step 5), quest action consume with the quest id.
Step 3 — Let the post-edit hook self-repair
Once the build-role quest's edits land, fairy-tales' post-edit hook automatically
runs the project's .pi/test-command (if present) and steers any failures back to
the agent loop to fix, retrying until tests pass or it gives up. Let this run to
completion rather than re-running tests manually. If .pi/test-command does not
exist in the project, say so explicitly in the phase summary — the fix was not
auto-verified by tests and bughunt-verify will need to lean more heavily on the
broader test suite it runs directly.
Step 4 — Checkpoint after
After the build-role quest's edit turn completes (and any self-repair loop
settles), fairy-tales' checkpoint extension automatically snapshots the working tree
(git stash create) at turn end. Confirm the new checkpoint exists via
/checkpoints and record its SHA/label as the after checkpoint. If verification
in the next phase fails, /rollback can restore to the before checkpoint.
Step 5 — Complete the phase
Call the chain tool:
action: "complete-phase", chain: "bughunt", phase: "fix",
summary: "fix implemented at <file:line> via build-role quest; checkpoint before <sha>; checkpoint after <sha/label>; test hook <ran and passed / ran and self-repaired N times then passed / not configured — no .pi/test-command>",
data: {
"fixSummary": "<what changed and why it addresses the root cause>",
"filesChanged": ["<path>", "..."],
"checkpointBefore": "<sha>",
"checkpointAfter": "<sha or checkpoint label from /checkpoints>",
"testHookResult": "<pass / self-repaired (N iterations) / not configured>"
},
artifacts: { "fixQuest": "<quest id>" }The tool validates this is the current phase, advances the run to verify, and
rewrites the JSON + markdown projection atomically.
Handoff
After completing this phase, output exactly:
Phase 3 complete. Chain state updated (
.pi/fairy-tales/chains/bughunt/state.json). Run/bughunt-verifyto begin Phase 4.
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.

