# debugger

_Status: direction — deferred (post-v1) — as of 2026-07-17_
_Connects to: [deterministic-gates](deterministic-gates.md), [pipeline-stages](pipeline-stages.md), [self-improvement-loops](self-improvement-loops.md), [agent-design-principles](agent-design-principles.md), [overview](../OVERVIEW.md)_

## Purpose

Names the stuck-path specialist that is deliberately *not* the reviewer, and defines its dual
identity: it solves the ticket the cheaper team couldn't, and it generates a harness-improvement
signal from *why* they got stuck. Load this only when the happy path is trusted and stuck runs
are worth investing in — not before.

## Design

- **Distinct from the reviewer, and added later.** The reviewer runs on the happy path where
  lint + tests already pass and only judgment remains ([pipeline-stages](pipeline-stages.md)).
  The debugger runs on the *stuck* path — triggered when the max-iteration cap in
  [deterministic-gates](deterministic-gates.md) escalates, i.e. a cheaper programmer/test-writer
  team could not reach green. Different job, different trigger; do not merge them.
- **Expensive by design, rare by frequency.** It only fires on escalation, so it is the one
  place opus-tier reasoning is unambiguously worth it — it is solving problems less-capable
  models already failed. Cost is amortized across all the runs that *didn't* need it.
- **Independent reconstruction, then diff.** Rather than debugging the stuck team's code
  in place, the debugger works the ticket from context on its own — its own tests, its own
  implementation — then compares that against what the stuck team produced. The delta is the
  diagnosis: it usually reveals *why* the original team stalled (a misread spec, a
  test-writer that boxed itself in, a gate whose feedback pointed the wrong way).
- **The diagnosis feeds the harness, not just the ticket.** That "why they got stuck" delta
  is an improvement signal for [self-improvement-loops](self-improvement-loops.md) — recurring
  stall causes become harness/prompt/gate fixes, so the *next* cheap team clears the same
  class of problem without escalating.
- **Lint-thrash is one of its named checks.** A programmer failing the *same* lint rule across
  iterations is a strong signal the rule's *explanation* — not the code — is at fault: the
  copy is failing to direct the fix. The debugger flags this as a lint-explanation-quality
  defect (see [self-improvement-loops](self-improvement-loops.md) for the copy-formula
  autoresearch loop it feeds), distinct from a genuinely hard ticket.
- **Not the adversarial reviewer.** Edge-case hardening / adversarial review is a separate,
  further-out role ([horizon](horizon.md)) — v1 targets 99% good-enough; the 1% edge cases
  wait. The debugger is a *stuck-solver*, not an attacker.

## Open questions

- Independent-reconstruction is the tentative mechanism, not settled — it may be cheaper to
  have the debugger inspect the stuck team's exhaust first and reconstruct only on a real
  miss. Decide against real stuck runs, not up front.
- What the debugger writes down when it succeeds (the improvement-signal format) and how it
  routes to [self-improvement-loops](self-improvement-loops.md) — shared audit-report format,
  or a bespoke stall-report?
- Threshold for "lint-thrash" (same rule N times) and whether that check lives in the gate
  itself (cheap, deterministic) rather than waiting for the debugger to notice.

## Sources

- [deterministic-gates](deterministic-gates.md) (max-iteration escalation — the trigger)
- [pipeline-stages](pipeline-stages.md) (reviewer, the happy-path counterpart)
- [self-improvement-loops](self-improvement-loops.md) (harness-improvement + lint-copy loops)
- 2026-07-17 design session (this doc's origin)