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/`)
|
## 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
@@ -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,
|
||||||
|
|||||||
@@ -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).
|
||||||
|
|||||||
@@ -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)
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
|
|||||||
@@ -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).
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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"
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user