Diagnosing bugs

Establish the mechanism behind an observed failure before repairing it. This skill owns diagnosis, not the production fix.

Begin lightly. Read the error, stack, existing reproduction or captured artifact, and recent relevant changes. If that evidence already distinguishes the mechanism, report it without manufacturing a longer process. Escalate only as uncertainty requires.

When the surrounding assignment already authorizes repair, establish the diagnostic outcome first, then continue as the same actor under the implementation or repair contract and include it in the final handoff. Do not end the pass or create another handoff merely because diagnosis was needed.

Bound the symptom

Record the exact observed symptom, affected user or system path, revision and environment, known trigger, determinism or observed failure rate, and material constraints. Separate what was observed from what was reported or inferred.

Keep secrets, private data, credentials, and unrelated payloads out of commands, notes, and returned evidence. Retain raw artifacts locally only when authorized; expose the minimum sanitized evidence needed to support the result.

Establish a diagnostic signal

Choose the narrowest faithful evidence path available: