agentleFS
KcAnomKcAnom/pi-fairy-tales-chains/skills/bughunt-fix/SKILL.md

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

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
  1. Very specific:

    All chain state is managed by the chain tool: authoritative JSON at .pi/fairy-tales/chains/bughunt/state.json with a human-readable …

    line 30
  2. Very specific:

    Call the chain tool with action: "status", chain: "bughunt" (a legacy .bughunt-state.md from an older version is imported automatically):

    line 37
  3. Very specific:

    If there is no run → abort: "No bughunt run found.

    line 40
  4. Very specific:

    If the run is not active with currentPhase: "fix" → abort: "Expected the run to be at phase fix but it is at <currentPhase/status>.

    line 41
  5. Very specific:

    If the diagnosis data (data.rootCause / data.location or the diagnose phase summary) is missing → abort: "Phase pointer looks right but the …

    line 44
  6. Very specific:

    If the tool reports the chain is locked by another session, abort.

    line 47
  7. Distinctive:

    Before any edit, record the current baseline so a bad fix is trivially reversible: run git status --short (working tree should be clean or …

    line 56
  8. Very specific:

    If the fairy-tales checkpoint extension has an existing checkpoint list, note the most recent one via /checkpoints as the fallback rollback …

    line 59
  9. Very specific:

    If the returned quest is already done (crash-resume case), use its stored result directly.

    line 76
  10. Distinctive:

    After the build-role quest's edit turn completes (and any self-repair loop settles), fairy-tales' checkpoint extension automatically …

    line 94
  11. Distinctive:

    Call the chain tool:

    line 102
  12. Distinctive:

    After completing this phase, output exactly:

    line 122
  13. Distinctive:

    Do not start the next phase.

    line 127

≈ “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.

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

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-repro first."
  • If the run is not active with currentPhase: "fix" → abort: "Expected the run to be at phase fix but it is at <currentPhase/status>. Run that phase's skill instead."
  • If the diagnosis data (data.rootCause / data.location or 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-verify to begin Phase 4.

Do not start the next phase. Do not offer to continue. Output only the handoff line and stop.

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.