docs: explore-notes convention + verification handoff for manual checks

2026-07-23 17:58:48 +02:00
parent 85c7e650c9
commit d6891b8bd4
4 changed files with 252 additions and 0 deletions
@@ -0,0 +1,38 @@
+# Explore-notes
+
+Distilled, reusable maps of complex subsystems, produced by deep code exploration.
+The goal: stop re-exploring the same subsystem from scratch in every new session.
+
+These sit **between** the CLAUDE.md files and the code:
+
+- **CLAUDE.md** — high-level orientation, hand-maintained, always-loaded.
+- **explore-notes** — deeper subsystem detail (flows, who-calls-whom, invariants) that is
+  too fine-grained for a CLAUDE.md but stable enough to be worth caching. Read on demand.
+- **code** — the only source of truth.
+
+## Rules
+
+- **Only stable structure.** Flows, responsibilities, entry points, invariants, relative
+  file paths. **No line numbers**, no exhaustive symbol dumps — those rot fastest.
+- **Verify before trusting.** A note is a starting map, not authority. Always confirm
+  against current code before acting on it. Each note records the commit it was verified
+  against so you can diff for drift.
+- **Not a substitute for CLAUDE.md.** If a fact belongs in orientation, put it there.
+
+## Header every note must carry
+
+```
+> **Explore-note — verify before trusting.** Distilled map of a subsystem, not authoritative.
+> Last verified against commit `<short-hash>` (<date>).
+> Drift check: `git log --oneline <short-hash>..HEAD -- <paths this note covers>`
+> Stable structure only (no line numbers). See docs/explore-notes/README.md.
+```
+
+## Workflow
+
+1. **Before** deep-exploring a subsystem, check for a matching note here and read it first;
+   explore only to fill gaps or confirm.
+2. **After** a deep explore, distill the durable findings into a new/updated note and bump
+   its "verified against" commit line.
+3. If the drift check shows the covered paths changed a lot since the verified commit, treat
+   the note as suspect and re-verify the parts you rely on.