janezicmatej/.dotfiles
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore(claude): rework rules and add notes policy

Browse Source
This commit is contained in:
Matej Janezic
2026-10-16 14:20:33 +00:00
parent 456a69bb8d
commit f265cef593
3 changed files with 97 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
claude/rules/diagnostics.md
View File

@@ -1,26 +1,8 @@
# 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.
The long form of the headline rules in `CLAUDE.md`.
## 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)
- Say what the cause is, with the evidence (file and line, log excerpt, command output), before proposing a fix. For system, boot, network and regression bugs, also say which other cause you ruled out and why.
- A workaround is labelled as one, with what would have to change to make it unnecessary. Don't mask an error with a try/except, a retry or a flag without asking first.
- If the fix doesn't resolve the symptom, go back to the cause; don't stack another patch on top.
- Done means the reported behaviour is now right, checked by re-running what failed. An error that went away is not enough. If the fix touched a process, daemon or background job, check it left nothing behind (processes, sockets, locks, temp files).