docs(memory): one WRITE section in capitalize-commit.md, every flow cites it; Index steps removed; doctrine names the single writer

This commit is contained in:
bchanot committed 2026-10-28 14:19:21 +01:00
1 parent 6c9bb7c58b
commit f15c360b95
12 files changed
+45 -38

No files matched your search

+4 -4
View File
@@ -107,8 +107,8 @@ code" wins. Repo-specific instructions override both.
## Memory registries (`.claude/memory/`) ## Memory registries (`.claude/memory/`)
Five registries persist across sessions; capitalize during and after work. Five registries persist across sessions; capitalize during and after work.
Append-only: never rewrite past entries; curation (merge, supersede, Append-only, written only through `bash ~/.claude/lib/memory.sh` (add,
compress) only via `/prune-memory`. status, journal), never by Edit; curation only via `/prune-memory`.
| File | ID | Purpose | | File | ID | Purpose |
|---|---|---| |---|---|---|
@@ -124,8 +124,8 @@ log → journal; whether the output actually worked → evals.
**Always English, always caveman**: drop articles and filler, fragments OK, **Always English, always caveman**: drop articles and filler, fragments OK,
short synonyms; technical terms, code blocks, quoted errors, IDs and dates short synonyms; technical terms, code blocks, quoted errors, IDs and dates
exact. Pattern `[thing] [action] [reason]. [next step].` Registries load exact. Pattern `[thing] [action] [reason]. [next step].` Planning flows
every session; caveman cuts ~40% of the tokens with no substance lost. read the registries; caveman cuts ~40% of every read, no substance lost.
Applies to direct writes and to the CAPITALIZE step of every completion Applies to direct writes and to the CAPITALIZE step of every completion
skill. Prompts to the user may mirror their language; the entry is English. skill. Prompts to the user may mirror their language; the entry is English.
Legacy entries: compress on demand via `/prune-memory`. Legacy entries: compress on demand via `/prune-memory`.
+1 -1
View File
@@ -96,7 +96,7 @@ A surfaced ID left undisposed is the gap this closes. You judge bearing; the mai
plan decides what to DO. plan decides what to DO.
Read-only here too: reading registries is within Read/Grep; the "Do not modify files" rule Read-only here too: reading registries is within Read/Grep; the "Do not modify files" rule
still forbids any write — Index backfill or new entries are never your job. Empty or absent still forbids any write — new entries or status lines are never your job (writes go through lib/memory.sh). Empty or absent
registries → omit the section (no-op). registries → omit the section (no-op).
Tracing what a destructive tool would do (a mirror, a sync with delete, a Tracing what a destructive tool would do (a mirror, a sync with delete, a
recursive rm, a deploy script) is done by reading it, never by running it, recursive rm, a deploy script) is done by reading it, never by running it,
+1 -4
View File
@@ -217,10 +217,7 @@ Otherwise:
hash and substitute `(ref step <n>)` → `(ref commit <hash>)` in every hash and substitute `(ref step <n>)` → `(ref commit <hash>)` in every
entry before writing. An entry that names no step (e.g. a pure LRN entry before writing. An entry that names no step (e.g. a pure LRN
pattern) needs no ref. pattern) needs no ref.
2. Append the resolved entries to their target registry file(s) 2. Write each resolved entry and one journal line for the batch per `$HOME/.claude/lib/capitalize-commit.md` § WRITE (`memory.sh -C <repo root> add …`, `memory.sh -C <repo root> journal …`; no Index to update).
(`.claude/memory/decisions.md`, `blockers.md`, `learnings.md`) and
update each file's `## Index` table. Add a one-line summary of the
commit batch to today's heading in `.claude/memory/journal.md`.
3. **Language rule**: written entries are ALWAYS in English and caveman, 3. **Language rule**: written entries are ALWAYS in English and caveman,
regardless of the language used in the dispatcher's approval exchange regardless of the language used in the dispatcher's approval exchange
(CLAUDE.md "Memory registries", Always English, always caveman). (CLAUDE.md "Memory registries", Always English, always caveman).
+3 -5
View File
@@ -39,8 +39,7 @@ blocker already solved.
no-match) → no-op naturally; only the ABSENT / no-file case needed the guard. The REGEX no-match) → no-op naturally; only the ABSENT / no-file case needed the guard. The REGEX
is the filter, not the file list: the glob also reads journal.md (date-keyed is the filter, not the file list: the glob also reads journal.md (date-keyed
`## YYYY-MM-DD`) and any non-entry file, which contribute zero matches — no need to `## YYYY-MM-DD`) and any non-entry file, which contribute zero matches — no need to
exclude them. Do NOT read the `## Index` table: it drifts (entries land in the body, the exclude them. Do NOT read a `## Index` table (v1 registries may still carry one; it drifted 32-40% on a mature repo; v2 has none); headings cannot drift.
manual Index update lapses — measured 32-40% missing on a mature repo); headings cannot.
3. SELECT — IDs whose title bears on $REQUEST. Judge on titles (one dense line each), not 3. SELECT — IDs whose title bears on $REQUEST. Judge on titles (one dense line each), not
on bodies. Over-inclusion is SAFE: an entry that proves non-binding costs one bare ref on bodies. Over-inclusion is SAFE: an entry that proves non-binding costs one bare ref
@@ -97,9 +96,8 @@ is not the current flow having TREATED it as a constraint. Re-surfacing is the f
## HARD RULE — read-only ## HARD RULE — read-only
Touches nothing. No write, no Index update, no memory mutation. Symmetric to Touches nothing. No write, no memory mutation. Symmetric to
capitalize-commit's surgical scope (there: stage ONLY memory; here: stage NOTHING). Index capitalize-commit's surgical scope (there: stage ONLY memory; here: stage NOTHING). Registry writes go through `lib/memory.sh`, never this snippet.
backfill, if ever wanted, is `/prune-memory` passe D — never this snippet.
## ORDERING (orchestrators only) ## ORDERING (orchestrators only)
+24 -4
View File
@@ -1,13 +1,13 @@
# CAPITALIZE-COMMIT — couple the memory commit to the dev flow # CAPITALIZE-COMMIT — couple the memory commit to the dev flow
Inline snippet. Include at the END of any dev flow's CAPITALIZE step, AFTER the Inline snippet for any dev flow's CAPITALIZE step: § WRITE says how the approved
approved registry / journal / TODO entries are written. It commits ONLY the registry and journal entries are written, then the rest commits ONLY the
memory, surgically, so the flow never leaves an uncommitted `.claude/memory` memory, surgically, so the flow never leaves an uncommitted `.claude/memory`
behind and never embarks dangling code. behind and never embarks dangling code.
This is the TAIL of capitalize, not a replacement: the SCAN + APPROVAL GATE that This is the TAIL of capitalize, not a replacement: the SCAN + APPROVAL GATE that
decide WHAT to write are unchanged and run before this snippet. Only the COMMIT decide WHAT to write are unchanged and run before this snippet; § WRITE then
of the already-approved entries is automated here. writes them through lib/memory.sh and the COMMIT is automated here.
## WHEN TO RUN ## WHEN TO RUN
@@ -29,6 +29,26 @@ If a flow should stay fully silent on a trivial run, that is the FLOW's gate
policy (e.g. hotfix skipping the journal line), not this snippet's concern — policy (e.g. hotfix skipping the journal line), not this snippet's concern —
tune it there. tune it there.
## WRITE (before the commit)
Registry entries and journal lines are written only by `lib/memory.sh`,
never by Edit or append; there is no `## Index` to update.
- Entry: caveman body to a scratch file, then
`bash "$HOME/.claude/lib/memory.sh" [-C <project root>] add
<decision|learning|blocker|eval> --title "<title>" --body-file <file>
[--status <status>] [--supersedes <ID>]`. One call per entry; it
allocates the ID under a lock and prints it. A blocker body quotes ≥1
error in backticks. `-C` when the cwd is not the project root.
- Status change on an existing entry:
`bash "$HOME/.claude/lib/memory.sh" status <ID> "<word> …"`, the text
starting with a status word (`resolved abc1234`, `open, reopened by …`,
`superseded by BDR-NNN`).
- Journal: `bash "$HOME/.claude/lib/memory.sh" journal "<line>"`.
- rc 2 names its reason (title chars, empty body, a status not starting
with a status word, an open code fence in the body or the registry,
unknown ID, lock busy): fix the input and re-run.
## DO ## DO
1. Compose the message from the IDs just written + the flow, matching repo style 1. Compose the message from the IDs just written + the flow, matching repo style
+1 -1
View File
@@ -272,7 +272,7 @@ A bugfix with an understood root cause is almost always worth one entry:
[LRN-XXX — <pattern>] (optionnel) [LRN-XXX — <pattern>] (optionnel)
Valider ? (all / blockers-only / edit / skip) Valider ? (all / blockers-only / edit / skip)
``` ```
4. Append approved entries + update the Index. Add a line to today's heading in `.claude/memory/journal.md`. 4. Write approved entries per `lib/capitalize-commit.md` § WRITE: a new blocker `add blocker … --status resolved`, an existing one now fixed `status <BLK-ID> "resolved <hash>"`, an LRN `add learning …` (no status); the journal line `memory.sh journal`.
**Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate may mirror the user's language; the appended entries must not. **Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate may mirror the user's language; the appended entries must not.
+5 -11
View File
@@ -140,7 +140,7 @@ with no dedup.
For every candidate from STEP 1 (and STEP 1B), check whether it is already For every candidate from STEP 1 (and STEP 1B), check whether it is already
captured before proposing it. Pull the distinctive keyword(s) of the candidate captured before proposing it. Pull the distinctive keyword(s) of the candidate
and grep the relevant registry (Index + bodies): and grep the relevant registry (headings + bodies):
```bash ```bash
# Example: candidate is a learning about "cd -P symlink resolution" # Example: candidate is a learning about "cd -P symlink resolution"
@@ -246,14 +246,8 @@ Registries first (in registry order), then the TODO.
Registry entries — for each approved: Registry entries — for each approved:
1. Read the target registry file. 1. Write each approved entry per `lib/capitalize-commit.md` § WRITE (`memory.sh add`, one call each; a resolved blocker: `memory.sh status <ID> "resolved <hash>"`).
2. Next sequential ID = scan existing `## <PREFIX>-NNN` body headings, take max, 2. Body in **caveman English** per CLAUDE.md memory format: drop articles +
+1 (e.g. last `## BDR-018` → `BDR-019`). Never reuse, never renumber.
3. Append the full entry at the **end** of the body (never rewrite existing
entries — append-only).
4. Add one row to the `## Index` table at the top: `| <ID> | <date> | <title>
| <status> |` (column set varies per file — match that file's header row).
5. Body in **caveman English** per CLAUDE.md memory format: drop articles +
filler, fragments OK, short synonyms. Keep code/URLs/error-quotes/IDs/dates filler, fragments OK, short synonyms. Keep code/URLs/error-quotes/IDs/dates
verbatim. Entries are ALWAYS English even if the STEP 3 prompt mirrored the verbatim. Entries are ALWAYS English even if the STEP 3 prompt mirrored the
user's language. user's language.
@@ -269,8 +263,7 @@ TODO — for each approved:
Write one timeline line under today's `## YYYY-MM-DD` heading — even if every Write one timeline line under today's `## YYYY-MM-DD` heading — even if every
candidate was skipped or already captured. candidate was skipped or already captured.
- Heading exists → append a bullet. - `bash "$HOME/.claude/lib/memory.sh" journal "<line>"` per bullet (it creates today's heading when missing).
- Missing → create `## YYYY-MM-DD` and write 3-5 bullets summarizing the session.
Reference any IDs written this run AND the TODO ops: Reference any IDs written this run AND the TODO ops:
`BDR-019 + LRN-026 capitalized; checked 1 done, added 1 task.` `BDR-019 + LRN-026 capitalized; checked 1 done, added 1 task.`
@@ -302,6 +295,7 @@ Follow `~/.claude/lib/capitalize-commit.md`:
- **rc 3** → unsafe git state (detached / merge / rebase) or not a git repo: - **rc 3** → unsafe git state (detached / merge / rebase) or not a git repo:
memory stays in the working tree, surface the helper's stderr, do NOT retry. memory stays in the working tree, surface the helper's stderr, do NOT retry.
The flush is safe on disk; STEP 6 must say NOT committed, not ✅-all. The flush is safe on disk; STEP 6 must say NOT committed, not ✅-all.
- **rc 5 / rc 6** → nothing committed; surface the helper's stderr; meaning and recovery in `lib/capitalize-commit.md` (rc 6: fix the registry, then /commit-change). STEP 6 says NOT committed.
- **rc 0, hash EMPTY → must NOT happen from this step.** STEP 5 always writes - **rc 0, hash EMPTY → must NOT happen from this step.** STEP 5 always writes
the journal line, so memory is ALWAYS pending at 5B → the helper always has the journal line, so memory is ALWAYS pending at 5B → the helper always has
≥1 change → the hash is non-empty by construction. An empty hash here means ≥1 change → the hash is non-empty by construction. An empty hash here means
+1 -1
View File
@@ -245,7 +245,7 @@ CAPITALIZE — proposé
Valider ? (all / <IDs> / edit / skip) Valider ? (all / <IDs> / edit / skip)
``` ```
Always append a 1-line entry to today's heading in `.claude/memory/journal.md`. Approved entries and the always-written 1-line journal entry: per `lib/capitalize-commit.md` § WRITE (`memory.sh add` / `memory.sh journal`).
**Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate may mirror the user's language; the appended entries must not. **Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate may mirror the user's language; the appended entries must not.
+1 -1
View File
@@ -231,7 +231,7 @@ Hotfixes are often trivial (typo, config, import) — skip by default. But if th
Default behaviour: `CAPITALIZE: hotfix trivial, skip` (no prompt, no output). Default behaviour: `CAPITALIZE: hotfix trivial, skip` (no prompt, no output).
Ask the user only when there is an actual candidate to propose. Ask the user only when there is an actual candidate to propose.
Always append a 1-line entry to today's heading in `.claude/memory/journal.md` (even trivial hotfix — journal is timeline, not signal). Always append a 1-line journal entry (even trivial hotfix — journal is timeline, not signal) and any approved BLK/LRN per `lib/capitalize-commit.md` § WRITE.
**Language rule**: the journal line and any proposed BLK/LRN entries are ALWAYS written English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). **Language rule**: the journal line and any proposed BLK/LRN entries are ALWAYS written English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman).
+1 -3
View File
@@ -298,9 +298,7 @@ capitalizes NOTHING. Do NOT fabricate a BDR to fill the step. Print
[ decisions.md ] BDR-XXX — <decision> — <1-line why> [ decisions.md ] BDR-XXX — <decision> — <1-line why>
Valider lesquels ? (all / <IDs> / edit / skip) Valider lesquels ? (all / <IDs> / edit / skip)
``` ```
3. Append approved entries to the existing registries (bootstrapped at STEP 5, 3. Write approved entries to the registries bootstrapped at STEP 5 (in the root commit), and the journal line, per `lib/capitalize-commit.md` § WRITE.
in the root commit) + update the Index. Append a journal line under today's
heading in `.claude/memory/journal.md`.
**Hash rule — founding decisions carry NO commit hash; use path + date only.** **Hash rule — founding decisions carry NO commit hash; use path + date only.**
This is by nature, not an omission: a founding decision is made at DESIGN This is by nature, not an omission: a founding decision is made at DESIGN
+1 -1
View File
@@ -1179,7 +1179,7 @@ per the project's commit convention), and verifies every rule is in
hash and `git -C <ROOT> show --stat <hash>`, the user decides. hash and `git -C <ROOT> show --stat <hash>`, the user decides.
S7 — AFTER. `claude -p "/context"` again from `<ROOT>`; append to that S7 — AFTER. `claude -p "/context"` again from `<ROOT>`; append to that
project's `.claude/memory/journal.md` under today's date: `CLAUDE.md project's journal (`bash "$HOME/.claude/lib/memory.sh" -C <ROOT> journal`): `CLAUDE.md
split: <k> sections → .claude/rules/ (<names>), always-on <before> → split: <k> sections → .claude/rules/ (<names>), always-on <before> →
<after>`. Tell the user the proof step: a fresh session in that project <after>`. Tell the user the proof step: a fresh session in that project
that Reads one file per rule, then `jq -c 'select(.memory_type=="Project" that Reads one file per rule, then `jq -c 'select(.memory_type=="Project"
+2 -2
View File
@@ -270,8 +270,8 @@ Feature shipped implies at least one design decision worth capturing. Run this B
Valider lesquels ? (all / <IDs> / edit / skip) Valider lesquels ? (all / <IDs> / edit / skip)
``` ```
4. Append approved entries to the registries. Update the Index table at the top of each file. 4. Write approved entries per `lib/capitalize-commit.md` § WRITE (`memory.sh add`, one call each; no Index to update).
5. Append a one-line entry to `.claude/memory/journal.md` under today's date heading (`## YYYY-MM-DD`). 5. Journal line: `memory.sh journal` (same section).
**Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate above may mirror the user's language; the appended entries must not. **Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate above may mirror the user's language; the appended entries must not.