.dotfiles/claude/rules/diagnostics.md

Diagnostics rules

Detailed root-cause discipline for system, boot, network, and regression bugs. The headline rules live in CLAUDE.md; this file is the long form.

Root-cause hypothesis

Before proposing any fix for a system/boot/network/regression bug, write a "Root cause hypothesis" section with these four parts:

1. Symptom — the observable behavior, copied verbatim where possible (error message, missing output, wrong value)
2. Proximate cause — the immediate trigger, with evidence (file path + line, log excerpt, command output)
3. Underlying cause — why the proximate cause occurred; the layer of indirection that makes the proximate cause possible
4. Ruled-out alternative — at least one other plausible hypothesis you considered and why you discarded it

Only after writing all four parts should you propose a fix.

Workaround discipline

• never present a manual workaround as a fix; if a workaround is the only option, label it explicitly as a workaround and describe what would need to change to make it unnecessary
• if a fix doesn't resolve the symptom on first try, don't layer another patch; revisit the hypothesis instead
• if you're tempted to add a try/except, retry loop, or feature flag to mask an error, stop and ask first

Verification

• before declaring a fix done, re-run the failing check and confirm the reported behavior is now correct
• "the error message disappeared" is not sufficient; confirm the underlying behavior matches what was expected
• if the fix touches a process, daemon, or background job, confirm it cleaned up after itself (no orphaned procs, sockets, locks, temp files)