diff --git a/CHANGELOG.md b/CHANGELOG.md index 2edc489..65102d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 0.1.1 - 2026-08-01 + +- Split development-note behavior into independent read and write gates. +- Require reading relevant project memory before diagnosis, planning, solution selection, implementation, resumption, or direction changes. +- Require targeted recovery of similar scenarios, user preferences, rejected approaches, overall direction, authoritative state, evidence, risks, and next actions. +- Add validation coverage to prevent regressions to write-only behavior. + ## 0.1.0 - 2026-07-16 - Add the reference `AGENTS.md` policy. diff --git a/README.md b/README.md index a88a709..f7603a6 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ - [`workflows/UPDATE.md`](workflows/UPDATE.md)：参考规范升级后的重新审阅流程。 - [`references/interview-schema.md`](references/interview-schema.md)：不可跳过的逐项访谈问题。 - [`references/rule-catalog.md`](references/rule-catalog.md)：稳定规则 ID、适用条件和来源映射。 -- [`skills/maintain-development-notes`](skills/maintain-development-notes)：可独立安装的开发笔记 Skill。 +- [`skills/maintain-development-notes`](skills/maintain-development-notes)：先读取既有项目记忆、再维护状态的开发笔记 Skill。 ## 使用方式 @@ -36,6 +36,7 @@ workflows/ADOPT.md 和 references/interview-schema.md 与我逐项讨论。 - **二次确认**：访谈确认不等于写入确认；写入前必须展示最终 diff。 - **最小修改**：保留用户现有内容、编码、BOM、换行和文件结构。 - **能力诚实**：平台不支持指定子代理模型或推理档位时，必须说明，不能声称已经配置。 +- **先读后做**：遇到问题、选方案或恢复工作时，先检索既有笔记中的相同场景、用户偏好、已否决方案、总体方向和权威状态，再调查和修改。 ## Skill 安装 diff --git a/reference/AGENTS.md b/reference/AGENTS.md index 5946e20..787351c 100644 --- a/reference/AGENTS.md +++ b/reference/AGENTS.md @@ -40,4 +40,4 @@ 24. 优先复用已有且版本兼容的 `node_modules`、Cargo target 和工具缓存，避免在多个工作树重复安装或构建；复用前必须确认路径和版本兼容，且不得覆盖现有目录。 25. 长时间命令结束后必须确认相关进程已经退出；不要遗留构建、测试、开发服务器、watcher 或后台 Agent 持续占用资源。 26. 如果用户报告卡顿、CPU/磁盘占用异常或系统无响应，应立即停止新增重型任务，先检查并收束现有进程，再采用更低并发或更小范围的验证方案。 -27. 当工作区或线程出现多功能、多分支/工作树/PR、频繁任务切换、长周期调查、安装回滚或需要跨上下文恢复的状态时，必须自动使用 `$maintain-development-notes` 判断并创建或更新开发笔记；普通聊天、一次性问题、简单单任务和短只读探索不得为了形式创建笔记。 +27. 当存在适用开发笔记时，在调查问题、选择方案、设计、修改、恢复工作或改变方向前，必须先使用 `$maintain-development-notes` 读取并检索：相同或相关问题/场景、用户偏好与不可妥协约束、已否决/失败/superseded/不安全方案及原因、总体产品与架构方向、最后验证的权威状态与证据、剩余风险和后续动作；即使本次不需要写笔记，也不得跳过读取。当工作区或线程出现多功能、多分支/工作树/PR、频繁任务切换、长周期调查、安装回滚或需要跨上下文恢复的状态，或已验证现实发生有意义变化时，再根据 Skill 门槛创建或更新开发笔记；普通聊天、无关一次性问题、无持续状态的简单单任务和不产生持久决策的短只读探索不得为了形式写笔记。 diff --git a/references/rule-catalog.md b/references/rule-catalog.md index 44ebd1a..c1dbd09 100644 --- a/references/rule-catalog.md +++ b/references/rule-catalog.md @@ -17,7 +17,7 @@ Use these IDs when discussing adoption and updates. They identify behavior, not | WRITE-001 | 21 | Keep final write ownership explicit and exploration read-only by default | General | | RES-001 | 22 | Apply the user-selected per-command worker policy only to supported tools | Tool- and preference-specific | | RES-002 | 23-26 | Limit simultaneous heavy work, reuse compatible caches, and clean up processes | Preference-specific | -| NOTES-001 | 27 | Apply the development-note complexity gate without creating ceremonial notes | Requires installed Skill | +| NOTES-001 | 27 | Read applicable development memory before acting, then apply a separate write gate without creating ceremonial notes | Requires installed Skill | ## Semantic Comparison Rules diff --git a/scripts/validate-repository.ps1 b/scripts/validate-repository.ps1 index 8d0561e..a825845 100644 --- a/scripts/validate-repository.ps1 +++ b/scripts/validate-repository.ps1 @@ -80,6 +80,21 @@ if (Test-Path -LiteralPath $skillPath) { if ($skill -notmatch '(?m)^description: .+$') { $failures.Add('Skill description is missing.') } + + foreach ($requiredPhrase in @( + 'Apply separate read and write gates', + 'Discover and read before acting', + 'the same or a related problem or scenario', + 'user preferences and non-negotiable constraints', + 'rejected, failed, superseded, or unsafe approaches', + 'the overall product, architecture, and release direction', + 'the last verified authoritative state and supporting evidence', + 'unresolved risks, pending validation, and ordered next actions' + )) { + if (-not $skill.Contains($requiredPhrase)) { + $failures.Add("Skill is missing read-before-act gate: $requiredPhrase") + } + } } $requiredQuestionIds = @( diff --git a/skills/maintain-development-notes/SKILL.md b/skills/maintain-development-notes/SKILL.md index 75e8c12..afc6976 100644 --- a/skills/maintain-development-notes/SKILL.md +++ b/skills/maintain-development-notes/SKILL.md @@ -1,15 +1,27 @@ --- name: maintain-development-notes -description: Create and maintain durable development notes for context recovery. Use automatically when a workspace or thread has multiple active features, branches, worktrees, PRs, repositories, risky local installations, repeated task switching, long-running investigations, or state that must survive compaction and handoff; also use when an existing development note needs synchronization. Do not use for ordinary chat, one-off questions, simple single-task or single-file changes, or short read-only exploration with no continuing project state. +description: Read, reconcile, create, and maintain durable development notes for context recovery. Use automatically when a workspace or thread has multiple active features, branches, worktrees, PRs, repositories, risky local installations, repeated task switching, long-running investigations, or state that must survive compaction and handoff; whenever an applicable note exists, also use it before diagnosing problems, planning, choosing an approach, resuming work, or changing direction so prior similar scenarios, user preferences, rejected approaches, overall direction, evidence, and open risks guide the work. Do not create or update notes for ordinary chat, unrelated one-off questions, simple self-contained changes with no continuing state, or short read-only exploration that produces no durable decision or risk. --- # Maintain Development Notes -Preserve verified project reality so a future agent can resume without repeating investigations, confusing branches, or losing safety constraints. +Preserve verified project reality so the current agent and future agents can recover context without repeating investigations, ignoring user preferences, retrying rejected approaches, confusing branches, or losing safety constraints. Treat a development note as operational memory: read it before it should influence work, then update it when verified reality meaningfully changes. -## Apply the complexity gate +## Apply separate read and write gates -Assess the gate silently before creating a note. +Apply the read gate before the write gate. + +### Read gate + +When an applicable development note exists, read the relevant parts before diagnosing, planning, choosing a solution, implementing, resuming work, changing direction, installing, releasing, or handing off. + +The read gate applies even when the current task is small and will not justify a note update. A small task can still depend on old decisions, user preferences, or a rejected approach. + +Skip reading only for casual conversation, general advice, or work clearly unrelated to the note's scope. + +### Write gate + +Assess the write gate silently before creating or updating a note. Create or adopt a development note when any hard trigger applies: @@ -28,7 +40,7 @@ Otherwise, create a note only when at least two complexity signals apply: - The conversation is long enough that compaction or handoff is likely to lose operational context. - Different artifacts have different ownership, safety boundaries, or release plans. -Do not create a note for: +Do not create or update a note solely for: - Casual conversation or general advice. - A one-off question with no continuing implementation state. @@ -36,15 +48,25 @@ Do not create a note for: - Short read-only exploration that produces no durable decision or risk. - Routine command output that is already captured adequately by source control or CI. -If the gate is not met, continue the task without mentioning development notes. +If the write gate is not met, continue without creating or updating a note. Still use any context recovered through the read gate. -## Discover before creating +## Discover and read before acting 1. Search the workspace for existing files such as `DEVELOPMENT_NOTES.md`, `DEV_NOTES.md`, `CODEX_DEV_NOTES.md`, `HANDOFF.md`, or a clearly equivalent project record. -2. Read applicable `AGENTS.md` instructions and the current snapshot sections of existing notes. -3. Reuse the authoritative note. Do not create a competing note merely because its filename differs from the preferred name. -4. If multiple notes exist, identify their responsibilities. Synchronize them only when their documented roles require it. -5. If authority is ambiguous or notes contradict each other, verify reality before editing. Ask the user only when repository evidence cannot resolve ownership safely. +2. Read applicable `AGENTS.md` instructions, then read the note's current snapshot, non-negotiable constraints, active workstreams, known risks, and immediate next actions. +3. Search the note for terms connected to the current task: symptoms, error text, feature names, paths, symbols, branches, tools, protocols, or user language. +4. Recover six kinds of operational memory before choosing an approach: + - the same or a related problem or scenario; + - user preferences and non-negotiable constraints; + - rejected, failed, superseded, or unsafe approaches and why they were rejected; + - the overall product, architecture, and release direction; + - the last verified authoritative state and supporting evidence; + - unresolved risks, pending validation, and ordered next actions. +5. Reuse the authoritative note. Do not create a competing note merely because its filename differs from the preferred name. +6. If multiple notes exist, identify their responsibilities and read the authoritative source for each relevant fact. Synchronize them only when their documented roles require it. +7. If authority is ambiguous or notes contradict each other, verify reality before acting. Ask the user only when repository evidence cannot resolve ownership safely. + +For long notes, start with the current snapshot and use targeted search. Do not load or repeat the entire history when only a small section is relevant. ## Choose the note topology @@ -55,13 +77,16 @@ If the gate is not met, continue the task without mentioning development notes. Read [references/note-schema.md](references/note-schema.md) before creating a new note or substantially restructuring an existing one. -## Verify reality before writing +## Reconcile memory with reality before acting or writing -Treat conversation history as a lead, not as authoritative state. +Treat conversation history and development notes as leads, not as substitutes for current evidence. - Verify relevant repository path, branch, HEAD, dirty state, remotes, and worktree role. - Verify PR, issue, CI, release, installation, version, backup, or hash state when it matters and tools permit. - Distinguish `implemented`, `tested`, `human-validated`, `published`, `merged`, `installed`, `pending`, and `superseded`. +- Compare a proposed approach with previously rejected or superseded approaches. Do not repeat one unless a relevant premise changed, and record that changed premise. +- Honor recorded user preferences and overall direction unless the user has changed them or verified reality makes them impossible. +- If live evidence invalidates the note, correct the current snapshot before relying on it for downstream decisions. - Record uncertainty explicitly. Never turn an assumption into a completed status. - Never copy secrets, API keys, auth files, tokens, private prompt history, or unnecessary personal data into notes. diff --git a/skills/maintain-development-notes/agents/openai.yaml b/skills/maintain-development-notes/agents/openai.yaml index 9852e46..ce36a7f 100644 --- a/skills/maintain-development-notes/agents/openai.yaml +++ b/skills/maintain-development-notes/agents/openai.yaml @@ -1,7 +1,7 @@ interface: display_name: "维护开发笔记" - short_description: "在复杂多分支项目中自动创建并持续维护可恢复的开发笔记" - default_prompt: "Use $maintain-development-notes to assess this project and maintain an accurate development note." + short_description: "先读取既有项目记忆，再维护复杂项目的可恢复开发笔记" + default_prompt: "Use $maintain-development-notes to read applicable development notes before acting, reconcile them with current evidence, and maintain an accurate recovery record." policy: allow_implicit_invocation: true