hazard-hunt

name	hazard-hunt
description	Hunt a codebase for issues (bugs, duplication, drift, inefficiency) under a statistical stopping rule — issues beget issues, and an area is only released after enough clean spend that the upper confidence bound on the remaining rate drops below its value threshold. Use when hunting bugs, auditing an area, deciding whether to keep looking, or when someone asks "is this clean yet?"

Hazard Hunt

The deep principle: finding an issue is evidence of more issues. Defects cluster. So hunting is not a checklist to complete — it is a measurement process with a statistically principled stopping rule. Most reviewers stop when the fix list feels long. That is exactly backwards: a long fix list means the hazard rate is high and you should keep going.

The model

Treat issue discovery in an area (a module, subsystem, idiom, or concern — you choose the partition, and record it) as arrivals in token-time.

• Spend is measured in probes. One probe = one focused review pass over one area with one lens (~one agent-attention-unit). Probes are your token proxy; count them honestly.
• Per area, track: probes (total), finds (total issues), and silence (consecutive probes since the last find).

The observed hazard for an area is λ = finds / probes.

The stopping rule

Let V = the value of an average issue in this area, denominated in probes (from the worth ledger if one exists; default V = 3). Stakes enter the rule only through V: a low-stakes area is one whose issues are worth little (set V = 1 and say so in the ledger), a load-bearing area's issues are worth more (V = 5+). There is no separate low-stakes floor — an earlier draft had one, and it contradicted the economics below.

• The one rule: release an area only when consecutive clean probes reach 3·V — for never-hit areas that means total probes, for hit areas silence since the last find. (Rule of three: after t clean probes the 95% upper bound on the rate is 3/t; hunting pays while λ·V > 1, so release requires 3/t < 1/V, i.e. t > 3V.)
• Every find resets silence to zero. Yes, this means a hot area can absorb many probes. That is the point — it is the areas that keep yielding that deserve the spend.
• Escalation on find: a find doesn't just reset the clock — it widens the neighborhood. Immediately probe: the same file end to end; the same idiom everywhere it occurs in the repo (grep for it); the same class of mistake in sibling modules. Clusters are found by following the first member home.

Probe integrity. Silence only counts from a trusted instrument. A probe whose tooling is suspect — a grep that might have been rewritten, a check that collapses "error" and "no match" into one exit path, a sample that didn't actually reach ground truth — counts as no probe at all, not as a clean one. When a result surprises you toward "clean", re-run it through the rawest instrument available before letting it advance the silence clock.

Never stop because you are bored, because the list is long, or because you "covered" the files. Stop only on silence or on an explicit budget ceiling — and if a budget ends the hunt early, say so: report which areas were released on silence and which were merely truncated. Silent truncation reads as "clean" and is a lie.

Lenses

Rotate lenses across probes so consecutive probes of an area are not redundant: correctness / edge cases; duplication (same logic twice, drifted copies); dead code and stale docs; efficiency (needless allocation, O(n²) lurking, chatty IO); interface sharpness (leaky abstractions, boolean parameters, stringly-typed seams); invariants that are assumed but never checked; error paths (what happens when this fails halfway?); and the empirical spot-audit — pull N real records/outputs and verify them against ground truth by hand (does the stored tweet match the live URL? does the cache entry match a fresh compute?). Data poisoning and silent drift are invisible to code review; only fresh empirical sampling finds them, and a single failed sample is a find that resets the clock like any other.

Seed the area priority from: open bugs (strongest signal — an open bug marks a hot area by definition), the unease map from model-sentiment, recent churn (git log --stat), and the intent ledger's load-bearing paths.

Ledger

Persist statistics to .forward/hunt.jsonl, one JSON object per probe:

{"ts":"2026-07-09T12:00:00Z","area":"ingest/dedup","lens":"error-paths","finds":2,"issues":["half-written batch on SIGTERM","retry drops idempotency key"],"head":"abc1234"}

Stamp each probe when it runs, not when the cycle is written up. A reconstructed timestamp is a false receipt; if the real time wasn't captured, write "ts": null and say so — an honest null outranks a neat fiction.

Cumulative per-area state is derived by replay, so past sessions' spend counts toward today's silence thresholds. Before hunting, replay the ledger: an area that earned its silence last week and hasn't changed since (git diff --stat <then>..HEAD) stays released; an area that changed gets its clock partially reset.

Fan-out

At scale, run probes as parallel subagents (Workflow or Agent tool), one area×lens per agent, and apply the stopping rule in the orchestrator between rounds — loop-until-dry, where "dry" is defined by the silence thresholds above, not by a fixed round count. Adversarially verify finds before counting them: a refuted find does not reset the clock.