feat(claude): improve CLAUDE.md

claude/rules/diagnostics.md

@@ -0,0 +1,26 @@
+# 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)