Bug Hunt

# Audit-Fix-Rescan Cycle

## When to Use

Use this multi-pass cycle when a single bug-hunt pass is not enough:

- Pre-release hardening (you want a clean codebase, not a "good-enough" one).
- Reviewing code generated by another agent or by yourself in a long session.
- Audit Mode (`/bug-hunt --audit`) over a substantial scope (>5 files, or any package you plan to ship).
- After landing several non-trivial fixes that may have shifted invariants in adjacent code.

A single pass tends to surface the loud bugs while leaving quieter ones in their shadow. The cycle below is the structured response.

## Why Iterate

Each pass exposes a different layer of defect:

1. The first read finds defects that are visible without context — null derefs, missing `await`, obvious resource leaks, unsanitized inputs.
2. The second read finds defects that were *masked* by the first layer — logic errors, edge cases, partial error handling that you missed because the loud bug was drawing attention.
3. The third read finds defects you *introduced* while fixing the first two — regressions, broken invariants, inconsistent error contracts across the new code.

Stopping at pass 1 ships a partially-fixed codebase. Stopping at pass 2 ships your own regressions. The fourth pass is the verification gate that says "no defects remain visible".

## The Cycle

```
audit  →  fix  →  rescan
  ▲                  │
  └──── not clean ───┘
```

Each iteration narrows the defect surface. Stop when convergence criteria are met (`references/convergence-criteria.md`).

## Pass Contracts

| Pass | Mode | Reads | Writes | Done When |
|------|------|-------|--------|-----------|
| 1. Surface | Automated + read-line-by-line | Files in scope | Fix list | Loud defects fixed or filed |
| 2. Re-read | Manual fresh-eyes review | Files touched in pass 1 | Fix list | No new findings on re-read |
| 3. Integration | Test suite + diff review | Whole change | Fix list | Tests green, no regressions |
| 4. Verify | Automated rescan | Files in scope | Audit report | Scanner exits clean |

The pass numbers are guidance — collapse to two passes for a small scope, expand to four-plus for security or pre-release work.

## Pass 1 — Surface (Loud Defects)

Run the audit-mode workflow already in `skills/bug-hunt/SKILL.md` (Audit Steps 1–4). Triage every finding into one of:

- **Real bug** → fix immediately, record file:line and the change.
- **False positive** → record why it is safe (validated by caller, type system rules it out, scope-based cleanup, etc.).
- **Defer** → mark for pass 2 if it needs more context to decide.

Output is the audit report at `.agents/research/YYYY-MM-DD-bug-<scope>.md` plus a list of files actually edited.

## Pass 2 — Re-read with Fresh Eyes

This is the pass agents skip and humans regret skipping. Reload every file you touched in pass 1 and read it again, top to bottom, asking:

- Did my fix change a precondition that other code in this file relies on?
- What edge cases did the original bug hide (empty input, single-element collections, boundary values, concurrent callers)?
- Are there structurally-similar patterns in the same file that have the same defect?
- Does the trace through related files still hold? (Imports, callers, tests.)

Treat this pass as a separate investigation. Do not let "I just looked at this" stop you from looking again.

## Pass 3 — Integration

Run the test suite, then read the change as a unit:

```bash
cd cli && go test ./...        # or pytest, npm test, cargo test
git diff <merge-base>..HEAD    # review the whole change, not just the latest commit
```

Look for: tests that started failing, new compiler/linter warnings, behavior shifts in code that imports what you changed, conflicting fixes across files. Regressions filed during this pass go back to pass 1 of the next iteration, not into the fix queue for the current cycle.

## Pass 4 — Verify

Run the same scanners and reads from pass 1 against the post-fix tree. The pass is successful onl