| name | nexus-implementation-fact-sync-protocol |
| description | 该 skill 定义了实现者在完成代码修改后同步 `.Nexus/0-fact/` 的协议，以确保 fact 与真实代码保持一致，并可被 Reviewer 审查。 |
目标
该 skill 用于约束实现者在实现完成后如何更新 .Nexus/0-fact/。
目标是：
- 让当前轮变更有对应 fact
- 让后续 agent 不必重新扫大量代码
- 让 Reviewer 能独立验证 fact 与真实代码的一致性
- 避免“代码改了，但事实缓存没跟上”
适用对象
核心原则
- 先完成代码，再同步 fact
- fact 必须反映当前真实代码
- 不得先写未来计划，再补代码
- 只同步本轮实际触达的代码文件
- 不要求一次性补齐整个仓库
- 只对本轮改动范围建立 / 更新 fact
- 只写已确认事实
- 不根据命名猜测
- 不写尚未实现的设计意图
- 不写未来可能改动
- fact 缺失不是 blocker，但 fact 漏同步是问题
- 旧 fact 不存在时，可以新建
- 若当前轮改了代码却不补对应 fact，视为实现不完整
- fact 与实现文档必须相互对应
- 实现文档必须列出 fact 路径
- fact 应覆盖实现文档中声明的重要变更
文件映射规则
对每个变更代码文件：
- 真实文件：
- fact 文件：
.Nexus/0-fact/src/foo/bar.ts.md
规则：
同步工作流
- 列出当前轮所有主要代码变更文件
- 为每个文件定位或创建对应 fact 路径
- 读取已有 fact {若存在}
- 对照真实代码更新 fact
- 确认以下内容是否需要同步：
- 对外入口
- 新接口
- 外部字段
- 关键状态
- 关键流程
- 错误路径
- 空值 / 边界行为
- 旧路径收口
- 将 fact 路径写入实现文档
- 返回前自检 fact 是否覆盖本轮关键变更
最低同步要求
每个被改动的关键代码文件，其 fact 至少应体现：
- 文件职责
- 本轮主要变化
- 关键函数 / 类 / 流程
- 对外语义变化
- 边界 / 错误 / 回退路径 {若本轮有变化}
UI 文件额外要求
若是 UI 相关文件，fact 还应补充：
- 页面 / 组件职责
- 关键 props / state 语义
- loading / empty / error / disabled 等状态覆盖
- 响应式规则
- 无障碍要点
- 删除 / 合并的旧 UI 入口
必须阻塞的情况
出现以下任一情况，应返回 BLOCKED：
- 无法确认代码真实行为
- 文件已改，但无法安全总结其关键语义
- 方案与真实代码冲突，导致无法判断应该记录什么
- scope 不足以完成必要 fact 同步
- 工具故障导致无法写入 fact
与 nexus-fact-cache-comment-style 的关系
.Nexus/0-fact/ 的写作风格与结构必须遵循：
SKILL:nexus-fact-cache-comment-style
本 skill 负责：
- 什么时候同步
- 同步哪些内容
- 如何保证与当前实现闭环对应
返回前自检
在结束前必须自检：
- 我是否已经为当前轮关键代码文件同步了 fact？
- 我是否遗漏了外部接口 / 字段 / 状态语义变化？
- 我是否把 fact 路径写进了实现文档？
- 我是否避免了写猜测或未来计划？
