hunt - from symptom to verified fix

A bug goes from the User's report to a fix proven against its cause, through fixed stages.

This skill runs on the fondue engine. Read protocol/engine.md at the plugin root, ../../protocol/engine.md from this skill's directory, before anything below. The engine holds state, turns, replies, rulings, review, and commits. This skill fills in the engine's hooks: stages, roles, artifacts, transitions, the turn table, and what counts as a Blocker.

Why a sibling of spec, not a mode

In a feature, the uncertainty is the design; in a bug, it is the diagnosis. The spec skill's plan stage, phase files and per-phase Coders manage a design across many phases. A bug has one cause and one fix, so they are ceremony here. What the engine gets right for bugs is kept and sharpened: the RESULT rule (run it, never read it), a reviewer who asks what else fits the evidence, and gates that fail today.

When to use it

Use it when the cause is unknown and finding it takes experiments: intermittent, distributed, load-dependent, or where a wrong diagnosis is cheap to ship and expensive to discover. A bug with a stack trace or a local repro whose fix follows from it needs none of this: red test, fix, green test, one commit. Neither does a bug found while building a feature, when the project fixes those on the feature branch in their own commit.

Glossary

The engine's glossary holds, with these additions:

• Spec - here, one bug. Kind - bugs: a bug's folder is fondue/bugs/<bug>/.
• Stage - one of report, hunt, fix, then the engine's done or abandoned.
• Role - the engine's User and Arbiter, and Hunter and Reviewer.
• Topic - hunt or fix. The author of both is the Hunter, and the reviewer of both the Reviewer.
• Subject - a diagnosis file (hunt) or a commit range (fix).
• Red commit - the commit that adds the regression check and nothing else. The check fails there.
• Approved artifact - the signed report.md, and the diagnosis a closed hunt approved. Changing one is a User question (engine: User questions).

Folder layout

fondue/bugs/
  <bug>/
    current-state.txt, roster.md, 99-user.md, stats.md     (engine)
    report.md
    hunt/
      01-diagnosis.md, 02-diagnosis.md, ...
    review/
      hunt/   00-request.md, 01-review.md, 02-answer.md, ...
      fix/    00-request.md, ...
    question.md      (engine: User questions)
    advice/          (engine: Advisors)
  archive/
    <bug>/

Stages

The spec starts as the engine's Starting a spec says, with first state report.

report

The User writes report.md, the bug's starting document: alone, with the Arbiter in one of the ways the engine's Starting a spec offers, or with any other AI help. The stage ends when the User signs it off; the Arbiter asks for the sign-off whenever it shows a draft (engine: Asking the User). The Arbiter commits and sets hunt:Draft.

hunt

The Hunter reads the knowledge base (engine: Knowledge base) to find its way into the code, then reproduces the bug, localizes it, finds the root cause, writes hunt/01-diagnosis.md and opens review/hunt/. Every accepted fix to a diagnosis goes into a new diagnosis file with the next free number. Diagnosis files are never edited.

The Hunter may commit diagnostic code - counters, logs, probes - and change the environments report.md allows. Each diagnostic commit is listed in the diagnosis. By the end of fix it is either kept as part of the fix, with a reason, or reverted.

The Reviewer reads report.md and the diagnosis, and judges whether the diagnosis is sound: every step of the causal chain stands on its RESULT, every observation in the Evidence is explained, and the evidence rules out every other cause that would produce it. They may read code and run local commands to test a claim. They never change an environment report.md gives the Hunter. Why the review starts from the diagnosis: the Hunter has done the hunt, and a second one costs about as much again. What guards against anchoring on the Hunter's story is the last check: a cause is shown only when its rivals are ruled out, so a rival the Hunter never considered is a finding.

The stage closes on verdict approved or closed. If the approved diagnosis has Outcome: exit, the next state is done, not fix (see Exit to a spec). A bug that will not reproduce, or is not worth the hunt, is abandoned as the engine says.

fix

The Hunter commits the regression check alone first: the red commit, which fails. Then they commit the fix and open review/fix/, under the engine's Code turns: every turn that changes code ends with the full build green and all tests passing. The red commit is the only commit allowed to be red, and only at the check it adds.

The Hunter also updates any project documentation the bug proved wrong or missing, e.g. a gotcha in a feature skill. When the project has a knowledge base, it brings that up to date too (protocol/kb.md). <sha> is the commit the bug's code changes start from: the parent of the first diagnostic commit the fix keeps, or of the red commit if it keeps none. The Hunter runs kb.py write --since <sha>, then kb.py status --since <sha> until it reads clean, and checks against the fix the project skills kb.py touched <sha> lists. The documents are committed on their own, after the fix. When fondue/kb/ is ignored, no card is staged and the request names the changed cards as files. There is no handover stage.

The stage closes on verdict approved or closed, and the next state is done.

Exit to a spec

When the root cause is real but its fix is a design change - a port, a contract, a module boundary - the diagnosis says Outcome: exit. The hunt still closes on approval, and the bug goes to done. The User may then open a spec. Its brief restates the facts it needs from the diagnosis, because an archived bug is history, not a source.

State

current-state.txt is <stage>[:<Step>], e.g. report, hunt:Review, fix:Answer, done.

Transitions

The engine's rows hold. This skill adds:

After an exit, the Arbiter tells the User the bug left for a feature spec. It is the one closing the User needs to hear about.

What the Arbiter does on a transition

• Fresh sessions. None. Each role is spawned once, before its first turn.
• Commit points. When the report is signed off and when the hunt closes.
• The writer's tokens. fix:Draft and fix:Answer may run kb.py write, so their replies get the engine's KB writer row (engine: stats.md).

Who reads and writes what

R = reads, W = writes (and reads). A role reads nothing in the spec that this table does not give it.

When the User asks, the Arbiter reads anything (engine: Roles every process has).

Roles

The engine's User and Arbiter, and:

• Hunter - author of the diagnosis and the fix. Lives for the whole bug.
• Reviewer - reviews the diagnosis and the fix. Lives for the whole bug.

The Arbiter stays although there are only two actors. Why: if the Hunter sends the Reviewer its turns, one party writes the reviewer's prompt and judges its own review. The Arbiter costs a reply line per turn; it buys neutrality.

Both actors live across both stages. Why: a spec spawns a fresh Coder per phase by default because a session kept across many phases re-reads its whole history. A bug has two stages and one fix. The Hunter's context of the hunt is the asset the fix needs, and a Reviewer who approved the cause is the one to check the fix against it.

Artifacts

report.md

Written and signed off by the User; the Arbiter writes its template, and a draft when the User asks (engine: Starting a spec).

# <bug title>

## Symptom
<what goes wrong, observed where, how often>

## Evidence
<runs, logs, metrics, commits and build ids - everything seen, with where it lives>

## Fixed means
<the observable that proves the fix. For a rate-based symptom: the live check and its sample size
(see The fix gate)>

## Environments
<what the Hunter may change: deploy to a test cluster, run a load tool, commit diagnostic code>

## Known and open
<suspicions, ruled-out causes, and what nobody knows yet>

## Out of scope                                   (optional)
<what the Hunter must not change, even if the fix would be easier>

hunt/NN-diagnosis.md

Owned by the Hunter, numbered from 01. Every claim is under the engine's Research rule: a FACT with its source or a RESULT with the command and its output. A cause read from the code, never run, is a hypothesis, not a finding.

# Diagnosis <NN>
Outcome: fix | exit

## Reproduction
<command, environment, output. It fails today, and it shows the mechanism, not just the symptom>

## Where it dies
<the point in the path, with the RESULT that localizes it>

## Root cause
<the causal chain, step by step, from trigger to symptom>

## Evidence accounted for
<each observation in report.md's Evidence, and how the cause explains it>

## Ruled out
<each rival cause, and the RESULT that killed it>

## Diagnostic commits
<sha - what it adds - keep or revert, and why>

## Fix
<what changes and the regression check that fails today. For exit: why the fix is a design change>

review/hunt/00-request.md

- **Subject:** hunt/01-diagnosis.md
- **Build:** <command> - green, <n> tests passed        (only if diagnostic code was committed)

review/fix/00-request.md

fix is a code topic. Its live check is reported as Live:, in place of Gates:, because it needs its result from before the fix too.

- **Subject:** git diff <from>..<to>
- **Red:** <red commit sha> - <check command> - fails: <the failure, one line>
- **Build:** <command> - green, <n> tests passed
- **Live:** <run> - before <result>, after <result>      (only when report.md's Fixed means asks for it)
- **Diagnostic commits:** <sha> kept (<why>) | <sha> reverted in <sha>
- **KB:** kb.py status --since <sha> - clean                 (only when the project has a knowledge base)

The hunt's closing verdict carries the outcome, e.g. Verdict: approved hunt/02-diagnosis.md | exit. Its reply's verdict field reads approved exit (or closed exit).

Turns

The engine's A turn, with this table:

What counts as a Blocker

Reviewing a hunt

A finding is a Blocker when:

• the reproduction shows the symptom through a mechanism other than the claimed cause. "I can make it fail" is not "this is why it failed"
• the causal chain has a step that is asserted, not shown
• an observation in report.md's Evidence is left unexplained
• another cause would produce the same evidence and the diagnosis does not rule it out by a RESULT, whether the Hunter named it or not. The finding names the rival and the evidence it fits
• the fix's regression check would pass on today's code

Anything else is a Nit.

Reviewing a fix

The Reviewer runs exactly two commands, and kb.py status, in place of the engine's one targeted command: the regression check at the red commit, where it must fail, and at the head of the range, where it must pass. They never rerun the build or the suite, which is trusted as reported. Why: for a feature, the build is the author's evidence. Here the red and green of one check are the evidence of the fix itself, and they are cheap to run. kb.py status spends no tokens.

A finding is a Blocker when:

• the check does not fail at the red commit, or fails for a reason other than the diagnosed cause (read the failure, not just the exit code)
• the fix treats the symptom, not the cause, e.g. a retry, a longer deadline or a swallowed error that hides the loss, unless the approved diagnosis showed a residual loss is inherent
• a diagnostic commit is neither kept with a reason nor reverted
• a card or a skill says something the fix made untrue, or kb.py status --since <sha> is not clean
• a live check that report.md asks for is missing, or its sample is too small (see The fix gate)
• the change is wrong, introduces a problem of its own, or breaks the project's rules

The fix gate

A fix is proven by a check that fails on the red commit for the diagnosed reason and passes after the fix. Prefer a deterministic test. When the bug shows only under live conditions, the live check is the Hunter's RESULT, trusted as reported like the build. Before and after are both recorded.

For a rate-based symptom, the "after" run must be large enough that the old rate would have produced at least 5 failures, and it shows 0. At an expected 5, a zero is chance about 0.7% of the time (e^-5). A run that small or smaller proves nothing.