58 lines
3.7 KiB
Markdown
58 lines
3.7 KiB
Markdown
# 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)
|