27 lines
1.6 KiB
Markdown
27 lines
1.6 KiB
Markdown
# 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)
|