peiiii / iteration-work-notes

Iteration Work Notes

概述

大型交付或查找/恢复已有大型交付时，先读取[大型交付记录协议](references/major-delivery-records.md)：新建默认 current-state.md，包含入口发现、当前状态与持续日志；旧入口兼容。下文是普通跨轮任务的轻量方法，不再并建一份记录。

这个 skill 用来把复杂任务和复杂 debug 的“易丢失上下文”外部化到项目已有的任务或迭代记录中。

目标不是写第二份 README.md，而是保证在以下场景里不会失忆：

• 上下文压缩
• 多次对话
• 长时间等待
• 中途交接
• 多轮实验后需要回看证据

何时使用

当任务满足以下任一特征时使用：

• 会跨多个阶段或多次对话
• 复杂 debug / 长链路排查
• 需要较长时间等待构建、发布、回归或线上观察
• 需要记录多条假设、证据、已排除路径与下一步
• 用户明确要求“记笔记”“保留过程”“避免上下文丢失”

以下情况通常不需要：

• 小而直接、单阶段、低风险的改动
• 纯措辞调整、轻量文档修补

默认落点

优先使用项目已有的任务记录目录；没有约定目录时使用 docs/work/YYYY-MM-DD-<task-slug>/working-notes.md，并从当前计划或设计链接它。日期取创建日，同任务跨天保持目录，已有记录不为日期前缀迁移。

规则：

• 默认先只用一个 working-notes.md
• 只有当内容明显分叉或持续膨胀时，才拆出更多文件
• 不要仅为了记笔记提前新建新的迭代目录

已有任务目录时直接更新；不为了笔记新建版本发布目录。若项目已有更严格的迭代命名合同，采用项目路径。

推荐结构

working-notes.md 默认至少包含以下模块：

1. 当前目标
2. 当前事实
3. 关键约束 / 不变量
4. 证据 / 观察点
5. 活跃假设
6. 已排除项
7. 关键决策
8. 下一步
9. 剩余缺口 / 交接提醒

其中：

• 当前事实 只写已经确认的事实，不混入猜测
• 活跃假设 只保留仍未被证伪的路径
• 已排除项 用来防止上下文压缩后重复踩同一个坑
• 下一步 应该足够具体，让下一轮直接接上

更新时机

至少在以下时刻更新一次：

• 进入新阶段前
• 做完一轮关键实验后
• 改变主要判断或主要方案后
• 进入长时间等待前
• 结束当前会话前

记录原则

• 记录事实、分歧点、决策和下一步，不写流水账
• 优先写“为什么现在相信 X / 不再相信 Y”
• 优先链接文件、路径、命令或结果摘要，不粘贴大段原始输出
• 保持当前真相源，不要让旧结论和新结论混在一起
• 如果某条结论过期，直接改掉或标注失效，不要堆版本噪音

何时拆分

只有出现下面情况时再拆更多文件：

• 证据量很大，working-notes.md 已明显过长
• 同时存在两个以上稳定子问题域
• 需要把 handoff、evidence、decision log 分开维护

推荐拆分方式：

• work/evidence.md
• work/decision-log.md
• work/handoff.md

拆分后仍要遵循一个原则：

• 当前计划、设计或任务入口必须链接这些文件

与任务 owner 的配合

• 本 skill 只负责跨轮事实载体，不反向编排调查或实施流程。
• 复杂多阶段实施：和主方案文档一起用。
• 需要交接：在 剩余缺口 / 交接提醒 中留下最小接手上下文。

反模式

• 把 work/ 写成第二份完整计划或迭代 README
• 把原始日志整段粘进去，几百行也不整理
• 只记现象，不记已排除项和下一步
• 关键决策只留在聊天里，不落到 work/
• 任务已经转向，但笔记仍停留在旧阶段

完成标准

只有满足以下条件，才算这份工作笔记真的有用：

1. 下一轮对话不看历史长聊天，也能快速接上
2. 已排除项和活跃假设是清楚分开的
3. 当前决策与下一步是可执行的
4. 当前任务入口能找到这份笔记