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:
1 parent
6c9bb7c58b
commit
f15c360b95
12 files changed
+45
-38
No files matched your search
+4
-4
@@ -107,8 +107,8 @@ code" wins. Repo-specific instructions override both.
|
||||
|
||||
## Memory registries (`.claude/memory/`)
|
||||
Five registries persist across sessions; capitalize during and after work.
|
||||
Append-only: never rewrite past entries; curation (merge, supersede,
|
||||
compress) only via `/prune-memory`.
|
||||
Append-only, written only through `bash ~/.claude/lib/memory.sh` (add,
|
||||
status, journal), never by Edit; curation only via `/prune-memory`.
|
||||
|
||||
| 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,
|
||||
short synonyms; technical terms, code blocks, quoted errors, IDs and dates
|
||||
exact. Pattern `[thing] [action] [reason]. [next step].` Registries load
|
||||
every session; caveman cuts ~40% of the tokens with no substance lost.
|
||||
exact. Pattern `[thing] [action] [reason]. [next step].` Planning flows
|
||||
read the registries; caveman cuts ~40% of every read, no substance lost.
|
||||
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.
|
||||
Legacy entries: compress on demand via `/prune-memory`.
|
||||
|
||||
+1
-1
@@ -96,7 +96,7 @@ A surfaced ID left undisposed is the gap this closes. You judge bearing; the mai
|
||||
plan decides what to DO.
|
||||
|
||||
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).
|
||||
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,
|
||||
|
||||
@@ -217,10 +217,7 @@ Otherwise:
|
||||
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
|
||||
pattern) needs no ref.
|
||||
2. Append the resolved entries to their target registry file(s)
|
||||
(`.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`.
|
||||
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).
|
||||
3. **Language rule**: written entries are ALWAYS in English and caveman,
|
||||
regardless of the language used in the dispatcher's approval exchange
|
||||
(CLAUDE.md "Memory registries", Always English, always caveman).
|
||||
|
||||
@@ -39,8 +39,7 @@ blocker already solved.
|
||||
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
|
||||
`## 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
|
||||
manual Index update lapses — measured 32-40% missing on a mature repo); headings cannot.
|
||||
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.
|
||||
|
||||
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
|
||||
@@ -97,9 +96,8 @@ is not the current flow having TREATED it as a constraint. Re-surfacing is the f
|
||||
|
||||
## HARD RULE — read-only
|
||||
|
||||
Touches nothing. No write, no Index update, no memory mutation. Symmetric to
|
||||
capitalize-commit's surgical scope (there: stage ONLY memory; here: stage NOTHING). Index
|
||||
backfill, if ever wanted, is `/prune-memory` passe D — never this snippet.
|
||||
Touches nothing. No write, no memory mutation. Symmetric to
|
||||
capitalize-commit's surgical scope (there: stage ONLY memory; here: stage NOTHING). Registry writes go through `lib/memory.sh`, never this snippet.
|
||||
|
||||
## ORDERING (orchestrators only)
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
# 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
|
||||
approved registry / journal / TODO entries are written. It commits ONLY the
|
||||
Inline snippet for any dev flow's CAPITALIZE step: § WRITE says how the approved
|
||||
registry and journal entries are written, then the rest commits ONLY the
|
||||
memory, surgically, so the flow never leaves an uncommitted `.claude/memory`
|
||||
behind and never embarks dangling code.
|
||||
|
||||
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
|
||||
of the already-approved entries is automated here.
|
||||
decide WHAT to write are unchanged and run before this snippet; § WRITE then
|
||||
writes them through lib/memory.sh and the COMMIT is automated here.
|
||||
|
||||
## 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 —
|
||||
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
|
||||
|
||||
1. Compose the message from the IDs just written + the flow, matching repo style
|
||||
|
||||
@@ -272,7 +272,7 @@ A bugfix with an understood root cause is almost always worth one entry:
|
||||
[LRN-XXX — <pattern>] (optionnel)
|
||||
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.
|
||||
|
||||
|
||||
@@ -140,7 +140,7 @@ with no dedup.
|
||||
|
||||
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
|
||||
and grep the relevant registry (Index + bodies):
|
||||
and grep the relevant registry (headings + bodies):
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
1. Read the target registry file.
|
||||
2. Next sequential ID = scan existing `## <PREFIX>-NNN` body headings, take max,
|
||||
+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 +
|
||||
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. Body in **caveman English** per CLAUDE.md memory format: drop articles +
|
||||
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
|
||||
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
|
||||
candidate was skipped or already captured.
|
||||
|
||||
- Heading exists → append a bullet.
|
||||
- Missing → create `## YYYY-MM-DD` and write 3-5 bullets summarizing the session.
|
||||
- `bash "$HOME/.claude/lib/memory.sh" journal "<line>"` per bullet (it creates today's heading when missing).
|
||||
|
||||
Reference any IDs written this run AND the TODO ops:
|
||||
`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:
|
||||
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.
|
||||
- **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
|
||||
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
|
||||
|
||||
@@ -245,7 +245,7 @@ CAPITALIZE — proposé
|
||||
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.
|
||||
|
||||
|
||||
@@ -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).
|
||||
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).
|
||||
|
||||
|
||||
@@ -298,9 +298,7 @@ capitalizes NOTHING. Do NOT fabricate a BDR to fill the step. Print
|
||||
[ decisions.md ] BDR-XXX — <decision> — <1-line why>
|
||||
Valider lesquels ? (all / <IDs> / edit / skip)
|
||||
```
|
||||
3. Append approved entries to the existing registries (bootstrapped at STEP 5,
|
||||
in the root commit) + update the Index. Append a journal line under today's
|
||||
heading in `.claude/memory/journal.md`.
|
||||
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.
|
||||
|
||||
**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
|
||||
|
||||
@@ -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.
|
||||
|
||||
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> →
|
||||
<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"
|
||||
|
||||
@@ -270,8 +270,8 @@ Feature shipped implies at least one design decision worth capturing. Run this B
|
||||
|
||||
Valider lesquels ? (all / <IDs> / edit / skip)
|
||||
```
|
||||
4. Append approved entries to the registries. Update the Index table at the top of each file.
|
||||
5. Append a one-line entry to `.claude/memory/journal.md` under today's date heading (`## YYYY-MM-DD`).
|
||||
4. Write approved entries per `lib/capitalize-commit.md` § WRITE (`memory.sh add`, one call each; no Index to update).
|
||||
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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user