cc-os/plugins/os-sdlc/reference/debugger.md

debugger

Status: direction — deferred (post-v1) — as of 2026-07-17 Connects to: deterministic-gates, pipeline-stages, self-improvement-loops, agent-design-principles, overview

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). The debugger runs on the stuck path — triggered when the max-iteration cap in deterministic-gates 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 — 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 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) — 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 — 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 (max-iteration escalation — the trigger)
• pipeline-stages (reviewer, the happy-path counterpart)
• self-improvement-loops (harness-improvement + lint-copy loops)
• 2026-07-17 design session (this doc's origin)