Define "a pointer is not a definition" once, in CLAUDE.md

This commit was merged in pull request #11.
This commit is contained in:
2026-09-24 22:01:13 +02:00
parent 5cc41487e6
commit 9ecfb1a99d
4 changed files with 4 additions and 3 deletions
+2
View File
@@ -94,6 +94,8 @@ How work proceeds in any repo, unless that repo's `AGENTS.md` says otherwise.
**Link, don't inline — and keep the link bare.** A mechanism identical across call sites or repos is documented once in the canonical source and pointed at with a one-line bare link; N copies drift, whether they are comments or READMEs. Don't summarize what's behind the link or restate the identifier's own name.
**A pointer is not a definition.** A definition the reader needs to follow the code — what a unit counts, what a term means, what invariant a cache rests on — sits at the code in one line. A pointer to it (`see AGENTS.md §11`) is the one comment form that cannot be checked against the code beside it, so it rots invisibly. A pointer carrying rationale — a rejected alternative, the premise behind a standing choice — is correct and stays.
### Comments
Default to NO comment. Delete one that is any of:
+1 -1
View File
@@ -110,7 +110,7 @@ Every PR gets at least this sweep; for sensitive surfaces also recommend the ded
- Are magic numbers/strings replaced with named constants?
- **Judge every comment and prose line the diff adds against `~/.claude/CLAUDE.md` → "Comments and documentation"**; report a density breach with the ratio and the files driving it.
- **Flag a caveat the diff has outlived**, anywhere in the repo: report the sentence's `file:line` and the behaviour that replaced it.
- **A pointer is not a definition.** Flag a comment whose content is a reference — `see AGENTS.md §11`, `per the spec §4` — when what it points at is a *definition* the reader needs to follow the code: what a unit counts, what a term means, what invariant a cache rests on. That belongs at the code, in one line. A pointer carrying *rationale* — a rejected alternative, the premise behind a standing choice — is correct and stays. Definitions in the code, reasoning in the record. A section number in another document is the one comment form that cannot be checked against the code beside it, so it rots invisibly.
- **Flag a pointer standing where a definition belongs** — `~/.claude/CLAUDE.md` → "Comments and documentation", "A pointer is not a definition".
- **Never propose new documentation as a "nice to have".** Suggesting a doc paragraph is proposing bulk someone must maintain. Raise it as a Stability Warning only when its absence would actively mislead someone, and say which mistake it prevents; otherwise don't raise it at all. Deleting redundant prose is always the cheaper fix.
- **Never let documentation stand in for a fix.** A finding is not closed by describing the defect in a README, and neither is one of yours: if the only available remedy is telling the reader, say so and mark it a decision for the human, so it lands in the PR or ticket where a decision record belongs. Naming a residual risk is your job; choosing to publish it in the repo is not yours to hand out.
+1 -1
View File
@@ -101,7 +101,7 @@ The bar is `~/.claude/CLAUDE.md` → "Comments and documentation"; per paragraph
- **Delete** — a type, a test name, a spec or the code already says it. In this chunk.
- **Move** — a decision goes to `docs/decisions.md` with its one-line index; a goal goes to the README. In this chunk.
- **Move back** — the opposite fault, and the one a deletion-only pass never catches. A comment that points at a definition (`see AGENTS.md §11` for what a unit counts, what a term means, what invariant a cache rests on) has put the wrong half in the record: definitions belong at the code in one line, reasoning belongs in the record. Inline the definition and leave the reasoning where it is.
- **Move back** — the opposite fault, and the one a deletion-only pass never catches: a pointer standing where a definition belongs ("A pointer is not a definition", same section). Inline the definition and leave the reasoning where it is.
- **Split or index** — load-bearing but unfindable: a section long enough that a reader who knows the answer is inside it still has to search for it. Sub-headings, or an index at its head. Bigger than the chunk → a `todo.md` item naming the section and what the hunt costs.
When §2's gate says the architecture pass is warranted, this pass widens with it: the fresh-context agent reads every prose file the repo owns rather than only the cited sections. That is the only sweep that catches accretion, since no diff shows a file that grew a paragraph per chunk.
-1
View File
@@ -4,7 +4,6 @@
Nine-seat comprehension panel, 2026-09-24, depth 1: Navigation 7.6, Locality 5.0, Shape 6.2, Self-sufficiency 5.3, overall 5.9. Every seat was capped by Locality or Self-sufficiency, and seven of nine named `bin/loop-claude`'s round loop as the unit they would least want to modify. The items below are ordered by how many seats named the place and how much of the cap it carries; each is one chunk.
- Move "a pointer is not a definition" into `CLAUDE.md` → "Comments and documentation" and cite it from `agents/stability-reviewer.md` §10 and `skills/larv-review/SKILL.md` §7, which each carry a copy today.
- Keep the pipeline order and the prose-only path in `skills/larv-review/SKILL.md` alone; its frontmatter, its §8 preamble, its §12 summary list and `CLAUDE.md`'s working loop each spell it today.
- State in `bin/loop-claude`'s docstring the Claude Code internals it rests on, with the version they were observed on (2.1.281): the transcript entry shapes `human_turns` reads, the `<id>.jsonl` file and its `.superseded-*`/`.orphaned-*` siblings, `~/.claude.json`'s `hasTrustDialogAccepted`, and `--json-schema` returning `structured_output`. Seven seats reconstructed these from the tests.
- Fix in `bin/loop-claude`: a judge failure re-judges after a minute instead of re-running the worker with "stopped before it was finished"; the failure counter survives a reload; `reload_if_edited` runs the new file with `--help` before exec so an import-time error keeps the old one; every directory `archive` creates is 0700, not only the leaf; `human_turns` states the list case positively; `project_path` and `session_name` share one branch; `sections` stops at any heading. Add a test for `run_round`'s resume decision against a stub `claude`.