From eca338012bb7e8fe14e158dc2f6e4cd428319147 Mon Sep 17 00:00:00 2001 From: tasuku-9 Date: Thu, 30 Apr 2026 08:29:19 +0900 Subject: [PATCH 1/2] Clarify routed memory update scope --- README.md | 4 ++++ SKILL.md | 28 ++++++++++++++++++++++++++++ tasks/update_memory.md | 18 +++++++++++++++++- templates/CONTEXT_MANIFEST.md | 9 +++++++++ templates/DOCS_GUIDE.md | 20 ++++++++++++++++++++ templates/README.md | 4 ++++ 6 files changed, 82 insertions(+), 1 deletion(-) 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..692d922 100644 --- a/SKILL.md +++ b/SKILL.md @@ -58,6 +58,31 @@ 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. + ## Language behavior Communicate with the user in the user's language by default. @@ -105,6 +130,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/update_memory.md b/tasks/update_memory.md index 5e8bc0b..8f368df 100644 --- a/tasks/update_memory.md +++ b/tasks/update_memory.md @@ -10,12 +10,28 @@ 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 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..60f0728 100644 --- a/templates/CONTEXT_MANIFEST.md +++ b/templates/CONTEXT_MANIFEST.md @@ -20,6 +20,9 @@ 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. + 1. `RECOVERY_NOTES.md` — latest resume checkpoint 2. `HUMAN_BRIEF.md` — human-facing project orientation 3. `CURRENT_STATE.md` — current truth @@ -87,6 +90,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 From 6f76503c7d2b0b0350964c96e30ed8332072fc55 Mon Sep 17 00:00:00 2001 From: tasuku-9 Date: Thu, 30 Apr 2026 08:39:14 +0900 Subject: [PATCH 2/2] Add read scope guidance --- SKILL.md | 10 ++++++++++ tasks/resume_work.md | 14 ++++++++------ tasks/update_memory.md | 4 ++++ templates/CONTEXT_MANIFEST.md | 2 ++ 4 files changed, 24 insertions(+), 6 deletions(-) diff --git a/SKILL.md b/SKILL.md index 692d922..fa3a6af 100644 --- a/SKILL.md +++ b/SKILL.md @@ -83,6 +83,16 @@ If you notice you are about to edit memory files without an update plan, stop an 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. 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 8f368df..440e13d 100644 --- a/tasks/update_memory.md +++ b/tasks/update_memory.md @@ -14,6 +14,10 @@ Do not treat tool-specific hidden memory as the canonical source of truth. 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 diff --git a/templates/CONTEXT_MANIFEST.md b/templates/CONTEXT_MANIFEST.md index 60f0728..83fd65e 100644 --- a/templates/CONTEXT_MANIFEST.md +++ b/templates/CONTEXT_MANIFEST.md @@ -22,6 +22,8 @@ If the repository also uses `AGENTS.md`, `CLAUDE.md`, or similar files, those fi 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