defect-diagnosis

Defect Diagnosis

Diagnose and fix from evidence; route prevention to product, architecture, development, testing, release or tooling.

• Code/test changes require self-checks; invoke code-review automatically before completion.

Non-Negotiable Rules

• Required failures, including inherited debt: diagnose, safely repair and rerun that check before handoff. Read repair-before-handoff. Working alternatives never close defects.
• Do not delete, comment out, or weaken a failing test just to make the suite pass.
• Do not call a workaround the fix unless the owner explicitly accepts the tradeoff and residual risk is recorded.
• Do not start broad refactoring while the cause is unknown. Isolate and fix first; refactor after the behavior is understood.
• Do not stop at "this line was wrong" when the defect reveals a missing contract, guardrail, test, review check, or skill rule.
• Do not state or act on a root-cause verdict — even as a confident aside — before you have read the failing owner's own evidence with your own eyes (assertion diff for a test, stack/exception for a crash, trace/log slice for a production symptom, source only when it is itself the failing artifact). Until then, label every cause as a hypothesis and name the evidence that would confirm or reject it. This applies to your OWN analysis, not only to LLM-proposed causes. Mitigation is exempt: you may roll back, flag-off, or shed traffic from symptoms while cause stays marked unknown — what is forbidden is choosing or applying a fix as though a cause is proven.

Phase A: Diagnose

1. Reproduce.
   • Record exact steps, inputs, environment, command, config, and observed failure.
   • Prefer a failing test, trace, payload, or smallest runnable reproduction.
   • If intermittent, record frequency, timing, data shape, and resource conditions.
   • A production symptom that cannot be re-triggered in place is not blocked on reproduction: diagnose from the failing run's own telemetry (step 4). Race or deadlock evidence may stay suggestive, but the cause still owes a falsifying probe before any fix.
   • Before declaring a bug non-reproducible — or an environment / service / tool / dataset needed to reproduce it "unavailable" or "blocked" — run the normal remediation for that layer first. Start the service / emulator / container / dependency and wait for readiness, run the repo setup or fixture/seed script, restart the client daemon, provision or refresh the test data, or try a different reproduction strategy (smaller or adversarial input, a different transport/endpoint, added tracing, or an engineered-interleaving / race-detector harness for a concurrency bug). Only record can't-reproduce / unavailable / blocked after the bounded remediation for that layer fails, with the command evidence, the residual risk, and the next concrete unblock action. A confident "I can't reproduce it" or "the env is down" with no remediation attempt is not a closed defect — it is pending.
     • This is not an escape hatch to never close or escalate. Remediation attempts are bounded and subject to the same frame-change / escalation discipline as hypotheses below (Frame-change-or-escalate, Escalation does not close the defect): after repeated failed bounded attempts, stop inventing new "different" strategies, escalate with a handoff packet, and keep the defect open under an owner — do not sit on an endless pending.
     • Safety preflight for any mutating remediation (setup / fixture / seed / data-refresh / daemon-restart, or docker compose up-style stack start): first prove the target endpoint, credential, and namespace are synthetic and disposable — never a live/prod/shared DB, API, token, or environment — and disable or isolate any side-effecting consumers, webhooks, or scheduled jobs the start would wake (they can process real queued events or reconnect to shared staging). If you cannot confirm the target is safe/scratch, the remediation is itself blocked — do not run destructive setup/refresh to chase a repro.