feat(claude): improve CLAUDE.md

.gitignore

@@ -123,3 +123,4 @@ claude/*
 !claude/CLAUDE.md
 !claude/settings.json
 !claude/statusline-command.sh
+!claude/rules

claude/CLAUDE.md

@@ -1,38 +1,36 @@
 # Global CLAUDE.md
 
-## Comments
+## Output format
+- for plans, reports, design docs, and anything benefiting from diagrams, styling, or embedded images, prefer HTML over Markdown
+- for conventional files (README, CONTRIBUTING, LICENSE, CHANGELOG, etc.) use the ecosystem default
 
-Comments must be one of two forms:
+## Diagnostics
+- IMPORTANT: pursue root cause before proposing a fix; never propose a manual workaround before identifying the underlying cause
+- if a fix doesn't resolve the symptom, dig deeper instead of layering patches
+- verify the fix addresses the reported behavior, not just that the error went away
+- for system/boot/network/regression bugs, write a root-cause hypothesis first (see ~/.config/claude/rules/diagnostics.md)
 
-```
+## Trust & verification
-# descriptive but non-verbose comment
+- IMPORTANT: don't present plausible-sounding details as facts; verify file paths, flags, function and library behavior by reading code or docs first
-# KEYWORD:(@janezicmatej) descriptive but non-verbose comment
+- when a claim depends on external behavior (library APIs, system semantics, game mechanics, etc.), cite the source you verified against, or mark it as unverified
-```
 
-Rules:
+## Planning vs execution
-- always lowercase
+- IMPORTANT: when asked to "plan", "analyze", "deep-dive", or "research", produce documents only; no Edit/Write (except to the plan file) or Bash mutations until approved
-- no trailing punctuation
+- if a request is ambiguous between planning and implementing, ask which one
-- keywords: WARN, FIX, NOTE, TODO, PERF, TEST, HACK
-- keyword comments must include attribution `(@janezicmatej)`
-
-## Git
-- commit only when asked or when delegating to agents
-- agents MUST commit with `--no-gpg-sign`
-
-## Workflow
-- implement changes directly; don't use sub-agents/Task for simple operations like renames, file moves, or single-file edits; only use Task for genuinely complex parallel exploration or research
-- when redirected or interrupted, immediately stop the current approach and follow the new direction; don't explain or defend the previous approach
-- focus on one goal per session; don't drift into unrelated improvements
-- use Task agents for research and exploration, not for straightforward implementation
 
 ## Scope
-- NEVER modify anything outside the scope of what was asked
+- if a diff grows beyond the original request, stop and confirm before continuing
-- don't introduce unrelated changes, touch unrelated configs, or change defaults not mentioned
-- if something related should change, ask first
 
-## Config locations
+## Workflow
-- MCP server configs go in `.claude.json` (project) or `$CLAUDE_CONFIG_DIR/.claude.json` (global, defaults to `~/.claude.json`), not `settings.json`
+- when redirected or interrupted, stop the current approach immediately and follow the new direction without explaining or defending it
-- `settings.json` is for permissions, hooks, and behavior settings
+- focus on one goal per session; don't drift into unrelated improvements
 
-## Code quality
+## Comments
-- after making changes, check if the project has linters/formatters and run them
+- lowercase, no trailing punctuation
+- plain: `# descriptive but non-verbose comment`
+- keyword: `# KEYWORD:(@janezicmatej) descriptive but non-verbose comment`
+- keywords: WARN, FIX, NOTE, TODO, PERF, TEST, HACK
+
+## Git
+- agents MUST commit with `--no-gpg-sign`
+- when implementing multi-step work, split into logical commits the user can review and stage independently; don't bundle everything into one

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)