From f265cef5935265d523cb976fc1707982696c4974 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Jane=C5=BEi=C4=8D?= Date: Fri, 16 Oct 2026 14:20:33 +0000 Subject: [PATCH] chore(claude): rework rules and add notes policy --- claude/CLAUDE.md | 28 ++++++------- claude/rules/diagnostics.md | 28 +++---------- claude/rules/notes.md | 78 +++++++++++++++++++++++++++++++++++++ 3 files changed, 97 insertions(+), 37 deletions(-) create mode 100644 claude/rules/notes.md diff --git a/claude/CLAUDE.md b/claude/CLAUDE.md index 0e56b5b..df3e63e 100644 --- a/claude/CLAUDE.md +++ b/claude/CLAUDE.md @@ -4,28 +4,24 @@ - 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 +## Notes +- local design docs, work handoffs and parked questions live in `.notes/` per project (see ~/.config/claude/rules/notes.md) + ## 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) +- IMPORTANT: find the root cause before proposing a fix; never present a workaround as a fix (see ~/.config/claude/rules/diagnostics.md) +- if a fix doesn't resolve the symptom, revisit the cause instead of layering patches ## Trust & verification - IMPORTANT: don't present plausible-sounding details as facts; verify file paths, flags, function and library behavior by reading code or docs first - 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 ## Planning vs execution -- 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 +- IMPORTANT: when asked to "plan", "analyze", "deep-dive", or "research", produce documents only; no Edit/Write (except to the plan file or `.notes/`) or Bash mutations until approved - if a request is ambiguous between planning and implementing, ask which one ## Scope -- if a diff grows beyond the original request, stop and confirm before continuing - -## Workflow -- when redirected or interrupted, stop the current approach immediately and follow the new direction without explaining or defending it -- focus on one goal per session; don't drift into unrelated improvements -- implement changes directly; don't use sub-agents/Task for simple operations like renames, file moves, or single-file edits -- use Task agents only for genuinely complex parallel exploration or research, not for straightforward implementation +- don't start unrelated work on your own; if a diff grows beyond the request, stop and confirm +- in orchestrated work (the `matej` skill), an agent working from a brief stays inside the brief instead: it notes anything outside it as a leftover and keeps going ## Comments - lowercase, no trailing punctuation @@ -35,5 +31,9 @@ - keyword comments must always include the `(@janezicmatej)` attribution ## 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 +- agents never sign commits, in any form: they are not me. commit with `--no-gpg-sign`; I re-sign branches on my host (`git sign-branch`) before they are pushed +- use the identity git already has; where it has none, commit as `-c user.name=agent -c user.email=agent@sandbox.invalid` (my host signing resets the author) +- commit messages: a conventional-commit subject line of at most 72 characters including the prefix; a body only where the project wants one, wrapped at 72; no trailers +- stage paths explicitly; never `git add .` or `git add -A` +- split multi-step work into a few logical commits I can review; condense fixups before handing a branch back +- every branch, worktree and container you create is yours to remove when the work ends; never remove ones you did not create diff --git a/claude/rules/diagnostics.md b/claude/rules/diagnostics.md index fa8ec26..9b81fec 100644 --- a/claude/rules/diagnostics.md +++ b/claude/rules/diagnostics.md @@ -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). diff --git a/claude/rules/notes.md b/claude/rules/notes.md new file mode 100644 index 0000000..96423d8 --- /dev/null +++ b/claude/rules/notes.md @@ -0,0 +1,78 @@ +# Notes rules + +Each project keeps its local working notes in `.notes/` at the project root: design docs, work that spans sessions, and questions parked for later. The notes are never committed to the project. The `notes` skill does the mechanics (creating the dir, picking ids, close-out). + +## Layout + +``` +.notes/ # its own git repo, never pushed + README.md # one line pointing here + index.html # generated: the overview, links only + notes.css # generated: copy of the skill's stylesheet every page uses + _pages/ # generated: questions, briefs and other markdown rendered to pages + _out/ # generated: other/out/ made self-contained, css inlined, for sending + docs/ # dNNN-slug.html, or dNNN-slug/index.html with its assets + work/ # wNNN-slug/ while in flight, removed at close-out + questions/ # qNNN-slug.md, removed when settled + other/ + in/ # placed by the user + out/ # prepared for someone else +``` + +- created on first need (the first doc, work item or question in a project), not up front +- the generated files are rebuilt by the skill's `notes.py` on every commit and never committed; browse every project's notes at once with `notes.py serve` (one port, roots `$NOTES_ROOTS`, else `~/git`), or one project with `python -m http.server -d .notes` +- every page has a back link to the index; ids like `d007` or `q014` in markdown become links + +## Numbering + +- `-`: `d` docs, `w` work, `q` questions; each letter has its own counter, three digits, lowercase kebab slug +- numbers are never reused, including numbers of deleted items: the next id is the highest ever used in that bucket (files plus `git -C .notes log --all --name-only`) + 1 +- refer to items by id everywhere: chat, other notes, commit subjects ("see q014", "per d007") +- `other/` is not numbered + +## docs + +- point-in-time design docs: plans, proposals, research, reviews; html per the output format rules +- one look for all docs: link `notes.css`, start `main.page` with `nav.back`, use only the components documented at the top of `notes.css`, no `