Debugging

Debugging in the harness starts from runtime evidence.

The flow begins with observed behavior: repro, log slice, trace, screenshot, browser observation, failing test, user-reported time window, or another concrete symptom. The agent filters noise, forms hypotheses from evidence, follows contradictions, inspects the smallest plausible code path, patches the bounded cause, and reruns the failing gate.

• Use this when: a concrete runtime symptom, failing check, log, trace, recording, or repro needs evidence-backed investigation.
• It gives you: hypothesis status, cited evidence, a bounded fix when proven, and rerun proof.
• It ends with: fixed behavior, a concrete blocker, or escalation to spec/delivery/debt when the cause is broader.
• Wrapped phase/skills: $debugging-phase, $debug-agent, optional $parallel-research, $review-phase.

Runtime Graph

Debug starts with the symptom, not the code smell. The graph is the evidence loop: observe, test hypotheses, patch the proven cause, rerun the failing gate.

Reading The Evidence Loop

• The operator gives symptom, environment, expected, actual. Without that, there is no failure to prove.
• $debug-agent gathers runtime evidence before edits: logs, repros, traces, screenshots, failing tests.
• $parallel-research is for independent readonly hypotheses, not a fishing expedition.
• Patch only the bounded cause the evidence supports.
• Rerun the failing gate before review. If the fix teaches durable runtime knowledge, route it to docs ingest.

Entrypoints

• $debugging-phase: run the runtime-evidence workflow.
• $debug-agent: gather logs, runtime observation, or manual testing evidence inside the debug flow. See External Tool Contract.
• $parallel-research: fan out readonly investigation across independent hypotheses.
• $review-phase: review the bounded patch.
• $docs-ingest-phase: downstream closeout when the fix changes operator workflow, runtime contracts, setup, or durable troubleshooting knowledge.

Evidence Discipline

Runtime evidence decides the investigation path. A code smell can suggest where to look, but it does not prove the failure. Logs, repros, browser observations, traces, failing tests, and time windows are stronger because they connect the patch to the behavior the user actually experienced.

When evidence contradicts the first hypothesis, the agent follows the evidence. When the evidence points outside the requested scope, the flow records a follow-up or debt item instead of hiding broader architecture work inside a debug patch.

Flow

Keep the debug loop evidence-first:

1. Invoke $debugging-phase with the symptom, environment, timestamp window, expected behavior, and actual behavior.
2. Let $debugging-phase gather logs, traces, browser screenshots, command output, or failing tests. Use $debug-agent when manual testing evidence or assisted log collection is needed.
3. Use $parallel-research for readonly hypothesis fan-out when the failure has independent possible causes.
4. Patch only the bounded cause identified by evidence.
5. Rerun the failing gate and any adjacent gate needed for confidence.
6. Invoke $review-phase for the patch.
7. Invoke $docs-ingest-phase from the owning closeout flow, or record a docs no-op.

Decision Points

• If evidence is missing, ask for or create a repro before patching.
• If logs contradict the suspected path, follow the logs.
• If the fix requires broad architecture work, capture a follow-up instead of hiding it inside a debug patch.

Terminal Outcome

The failure has an evidence-backed cause, a bounded fix, rerun validation, and clear residual risk.

Validation

Report the evidence used, the root cause, changed files, rerun commands or browser checks, and any runtime scenario that still needs manual confirmation.

See Validation Gates for the proof standard that decides whether the rerun evidence is enough.