nexus-implementation-fact-sync-protocol

name	nexus-implementation-fact-sync-protocol
description	该 skill 定义了实现者在完成代码修改后同步 `.Nexus/0-fact/` 的协议，以确保 fact 与真实代码保持一致，并可被 Reviewer 审查。

目标

该 skill 用于约束实现者在实现完成后如何更新 .Nexus/0-fact/。 目标是：

• 让当前轮变更有对应 fact
• 让后续 agent 不必重新扫大量代码
• 让 Reviewer 能独立验证 fact 与真实代码的一致性
• 避免“代码改了，但事实缓存没跟上”

适用对象

• Generalist
• UI_Coder

核心原则

1. 先完成代码，再同步 fact

• fact 必须反映当前真实代码
• 不得先写未来计划，再补代码

2. 只同步本轮实际触达的代码文件

• 不要求一次性补齐整个仓库
• 只对本轮改动范围建立 / 更新 fact

3. 只写已确认事实

• 不根据命名猜测
• 不写尚未实现的设计意图
• 不写未来可能改动

4. fact 缺失不是 blocker，但 fact 漏同步是问题

• 旧 fact 不存在时，可以新建
• 若当前轮改了代码却不补对应 fact，视为实现不完整

5. fact 与实现文档必须相互对应

• 实现文档必须列出 fact 路径
• fact 应覆盖实现文档中声明的重要变更

文件映射规则

对每个变更代码文件：

• 真实文件：
  • src/foo/bar.ts
• fact 文件：
  • .Nexus/0-fact/src/foo/bar.ts.md

规则：

• 保留原相对路径
• 保留原文件名
• 末尾追加 .md

同步工作流

1. 列出当前轮所有主要代码变更文件
2. 为每个文件定位或创建对应 fact 路径
3. 读取已有 fact {若存在}
4. 对照真实代码更新 fact
5. 确认以下内容是否需要同步：
   • 对外入口
   • 新接口
   • 外部字段
   • 关键状态
   • 关键流程
   • 错误路径
   • 空值 / 边界行为
   • 旧路径收口
6. 将 fact 路径写入实现文档
7. 返回前自检 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 路径写进了实现文档？
• 我是否避免了写猜测或未来计划？