diagnose — Root-Cause Isolation

Operating Invariants

Investigation Boundary: Read production source and existing tests; write temporary harnesses, fixtures, trace replays, and report files only inside .agents/scratch/. End at a root-cause report; leave production fixes, permanent tests, and fix changesets to subsequent work.
Working Tree Preservation: Preserve pre-existing changes and scratch artifacts. Run probes against isolated copies or existing read-only seams; keep instrumentation out of production source. Tag temporary probes [DEBUG-<hex>] and remove only session-owned instrumentation after collecting evidence.
Sensitive Evidence & Environment: Redact secrets before logging; never inspect secret files (.env*, *.key, *.pem). Ground runners in .agents/environment.md; confine execution strictly to local scratch boundaries without touching production or host-level containers.

Accept a defect description, error, log, stack trace, or reproduction. Identify expected behavior, observed behavior, relevant environment, and the execution seam; distinguish missing evidence from contradicted evidence.
Begin investigation with available evidence even when an executable RED is unavailable. Treat a failing assertion as symptom evidence; establish cause through a discriminating probe, a conclusive execution trace, or a verified causal chain.
Separate trigger and context from the mechanism that produces the failure. For each defensible hypothesis, state a prediction: If <cause>, then <controlled probe> changes <observation>.
Test competing explanations when evidence permits; vary one causal factor at a time and record results that support or falsify each candidate. Prefer direct traces for obvious syntax errors or deterministic failures over unnecessary harnesses.