diff --git a/README.md b/README.md index dbf6510..4a523ba 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,10 @@ The skill separates project knowledge into canonical markdown files, each with a The AI agent maintains these files during the session. The human usually doesn't write them directly. +project-memory is not a checklist of files to update every time. +It is a routed memory system: agents update only the canonical files whose responsibility changed. +Most sessions update 1-3 files, not the whole memory set. + ## What makes this different **Promotion rules** — A hypothesis cannot be promoted to `CURRENT_STATE.md` without evidence in `RESEARCH_LOG.md` or an explicit decision in `DECISION_LOG.md`. This prevents unverified ideas from silently becoming project assumptions. diff --git a/SKILL.md b/SKILL.md index 8f97cad..fa3a6af 100644 --- a/SKILL.md +++ b/SKILL.md @@ -58,6 +58,41 @@ Capture broadly. Promote narrowly. Do not let hypotheses, plans, or recovery notes silently become truth. +## Routed memory rule + +Project memory is not a full-file synchronization system. + +Do not read or update every project-memory file on every run. +Do not treat the file list or read order as a checklist. + +Each piece of information should go to its canonical home. +Update only the files whose canonical responsibility changed. + +Most work sessions should update only 1-3 files. +Larger updates are appropriate only during major transitions, such as phase changes, major hypothesis confirmation or rejection, architecture or approach changes, release checkpoints, or large migrations. + +Before editing memory files, produce a short update plan stating: + +- which files will be updated +- why each file needs an update +- which relevant files will not be touched + +For a small, obvious one-file update, a one-sentence plan is enough. +If you notice you are about to edit memory files without an update plan, stop and produce the plan first. + +When one piece of information seems to belong in multiple files, choose one canonical home according to `DOCS_GUIDE.md` and `CONTEXT_MANIFEST.md`. +Other files may reference the canonical entry, but should not duplicate the full details. + +## Read scope rule + +Start with `CONTEXT_MANIFEST.md` when present. + +Do not preemptively read the full memory set. +Use the read order as a priority order, not as a checklist. + +Before reading additional memory files, identify which files are relevant to the current task. +For non-trivial work, briefly state which memory files will be read and which relevant files will not be read. + ## Language behavior Communicate with the user in the user's language by default. @@ -105,6 +140,9 @@ If the repository also uses `AGENTS.md`, `CLAUDE.md`, or similar tool-facing gui When resuming or migrating a project, read in this order unless `CONTEXT_MANIFEST.md` says otherwise: +This is a priority order for orientation, not a checklist to exhaust on every run. +Read only as far as needed to route the current task safely. + 1. `CONTEXT_MANIFEST.md` 2. latest entry in `RECOVERY_NOTES.md` 3. `HUMAN_BRIEF.md` diff --git a/tasks/resume_work.md b/tasks/resume_work.md index 22bb412..4d16b99 100644 --- a/tasks/resume_work.md +++ b/tasks/resume_work.md @@ -5,12 +5,13 @@ Use this when a user wants to continue after chat loss, a long pause, or model m ## Process 1. Read `CONTEXT_MANIFEST.md` if present. -2. Read the latest checkpoint in `RECOVERY_NOTES.md`. -3. Read `HUMAN_BRIEF.md` for orientation. -4. Read `CURRENT_STATE.md` before trusting old claims. -5. Read only the relevant parts of `ROADMAP.md`, `DECISION_LOG.md`, `RESEARCH_LOG.md`, and `HYPOTHESIS_LAB.md`. -6. Identify conflicts instead of smoothing them over. -7. Return a compact restart plan. +2. Identify which memory files are relevant to the current resume task; do not preemptively read the full memory set. +3. Read the latest checkpoint in `RECOVERY_NOTES.md` when relevant. +4. Read `HUMAN_BRIEF.md` for orientation when relevant. +5. Read `CURRENT_STATE.md` before trusting old claims when relevant. +6. Read only the relevant parts of `ROADMAP.md`, `DECISION_LOG.md`, `RESEARCH_LOG.md`, and `HYPOTHESIS_LAB.md`. +7. Identify conflicts instead of smoothing them over. +8. Return a compact restart plan. Treat repository docs as the durable memory layer. Do not assume a tool-specific memory feature contains the full truth. @@ -51,6 +52,7 @@ Treat repository docs as the durable memory layer. Do not assume a tool-specific ## Common mistakes - Reading raw logs before canonical docs. +- Treating the read order as a checklist. - Treating recovery notes as the whole truth. - Treating hypotheses as facts. - Reconstructing old context from memory when files disagree. diff --git a/tasks/update_memory.md b/tasks/update_memory.md index 5e8bc0b..440e13d 100644 --- a/tasks/update_memory.md +++ b/tasks/update_memory.md @@ -10,12 +10,32 @@ The AI agent should route and write updates during the chat or coding session. Treat repository markdown files as the durable shared memory layer. Do not treat tool-specific hidden memory as the canonical source of truth. +## Update scope protocol + +Project memory is a routed memory system, not a checklist of files to update every time. + +Before reading beyond `CONTEXT_MANIFEST.md`, identify which memory files are relevant to the current update. +For non-trivial work, briefly state which files will be read and which relevant files will not be read. +Do not preemptively read the full memory set. + +Before editing memory files, produce a short update plan that says: + +- which files will be updated +- why each file needs an update +- which relevant files will not be touched + +Then apply only the necessary changes. +Most sessions should update 1-3 files. +Larger updates are appropriate only for major transitions such as phase changes, major hypothesis confirmation or rejection, architecture or approach changes, release checkpoints, or large migrations. + +If you are about to edit memory files without an update plan, stop and produce the plan first. + ## Process 1. Read `CONTEXT_MANIFEST.md` if present. 2. Read the latest `RECOVERY_NOTES.md` checkpoint. 3. Read `HUMAN_BRIEF.md` and `CURRENT_STATE.md`. -4. Read only the relevant parts of `ROADMAP.md`, `DECISION_LOG.md`, `RESEARCH_LOG.md`, and `HYPOTHESIS_LAB.md`. +4. Read only the relevant parts of `ROADMAP.md`, `DECISION_LOG.md`, `RESEARCH_LOG.md`, and `HYPOTHESIS_LAB.md`; do not treat the file list as a checklist. 5. Classify each new piece of information by status. 6. Write patch-ready updates only to the files that should change. 7. After routing updates, check whether the human-facing picture changed. diff --git a/templates/CONTEXT_MANIFEST.md b/templates/CONTEXT_MANIFEST.md index 91c1636..83fd65e 100644 --- a/templates/CONTEXT_MANIFEST.md +++ b/templates/CONTEXT_MANIFEST.md @@ -20,6 +20,11 @@ If the repository also uses `AGENTS.md`, `CLAUDE.md`, or similar files, those fi ## Read first +This is a priority order for orientation, not a checklist. +Read only the files needed to understand and route the current work safely. +Do not preemptively read the full memory set. +For non-trivial work, briefly state which memory files will be read and which relevant files will not be read. + 1. `RECOVERY_NOTES.md` — latest resume checkpoint 2. `HUMAN_BRIEF.md` — human-facing project orientation 3. `CURRENT_STATE.md` — current truth @@ -87,6 +92,12 @@ If private material matters, summarize it and link to the private location only ## Update policy +Project memory is routed by responsibility. +Update only the canonical files whose responsibility changed. +Most sessions should update 1-3 files, not the whole memory set. + +Before editing memory files, produce a short update plan listing the files to update, why they need updates, and relevant files that will not be touched. + Update this file when: - the canonical file set changes diff --git a/templates/DOCS_GUIDE.md b/templates/DOCS_GUIDE.md index ada5d4b..a5d56ee 100644 --- a/templates/DOCS_GUIDE.md +++ b/templates/DOCS_GUIDE.md @@ -12,6 +12,26 @@ The AI agent should update them during the chat or coding session. Treat repository markdown files as the durable shared memory layer. Do not treat tool-internal memory as the canonical source of truth. +## Routed memory rule + +Project memory is not a full-file synchronization system. +Do not read or update every project-memory file on every run. + +Information should be routed to its canonical home. +Update only the files whose responsibility changed. +Most sessions should update 1-3 files, not the whole memory set. + +Before editing memory files, produce a short update plan covering: + +- which files will be updated +- why each file needs an update +- which relevant files will not be touched + +For small, obvious one-file updates, a one-sentence plan is enough. + +If information seems to belong in multiple files, choose the most canonical file using this guide and `CONTEXT_MANIFEST.md`. +Other files may reference the canonical entry, but should not duplicate the full details. + ## Language policy - Communicate with the human in their preferred language when practical. diff --git a/templates/README.md b/templates/README.md index e2d4ab3..c037cb2 100644 --- a/templates/README.md +++ b/templates/README.md @@ -11,6 +11,10 @@ It should answer: It should not carry the full current truth, full decision history, raw research log, or recovery checkpoints. +project-memory is not a checklist of files to update every time. +It is a routed memory system: update only the canonical files whose responsibility changed. +Most sessions update 1-3 files, not the whole memory set. + ## Purpose