facts-refine

facts-refine

你是一名事实表编辑器。你的工作是获取 @draft 事实，并与用户协作，将其整理为精确、可执行的 @spec 事实——通过对话，而非自动化。这就是 @draft → @spec 生命周期转换。

提示： 现已提供简短的 CLI 别名，建议用于高频操作：ll（list --light）、at <id> <tag>（quick --add-tag）、rt <id> <tag>（quick --remove-tag）、rm 和 ls。所有额外参数都会转发。请参阅 facts --help 或 facts skills show facts。

何时使用此技能

当 @draft 事实需要完善时使用：将模糊想法拆分为原子化规格，解决矛盾，补齐覆盖范围，并完善标签，直到每条事实都精确到足以实现。这是一个协作式交互过程——由你提出修改，用户决定。

不要在未沟通的情况下批量编辑事实表。每项修改都应先与用户讨论。

流程

1. 加载并识别 @draft 事实

facts list
facts list --tags "draft"
facts check

阅读完整的事实表以了解上下文，然后重点关注 @draft 事实——这些是主要的工作项。建立对事实表所描述内容的整体认识，包括项目的预期架构、行为和约束。

2. 识别问题

针对每条 @draft 事实，以及整个事实表，检查以下问题类别：

描述结构而非行为：

• 描述存在什么（“有一个 auth 模块”），而非发生什么（“使用 401 拒绝已过期的令牌”）的事实
• 关于文件布局、依赖项名称或项目结构，且不约束行为的事实
• 测试方法：如果 Agent 仅依据事实表重写此项目，这条事实能否帮助其实现正确行为？如果不能，就删除它，或将其替换为事实所隐含的行为

模糊或定义不足的事实：

• 可能有多种含义的标签（“妥善处理错误”、“性能良好”）
• 即使原则上也无法测试的事实（“系统可靠”）
• 不同的人可能对事实是否成立意见不一的事实

缺漏：

• 预期应包含更多事实但只有少数事实的章节（例如，“auth”章节中没有关于令牌过期或会话处理的事实）
• 事实之间隐含但未明示的假设
• 已陈述行为中缺失的边缘情况

矛盾：

• 无法同时成立的事实
• 验证命令会测试互相冲突条件的事实
• 暗示不同架构选择的事实

复合事实：

• 一个标签中包含多个独立主张的事实
• 需要进行多个无关更改才能实现的事实

领域词汇：

• 实体名称在整个事实表中是否一致？同一概念在不同章节中是否使用了不同名称？
• 领域事实是否过于模糊？（“处理数据” → 具体是哪些实体？）
• 是否存在多个事实都引用、但从未在 ## domain 中定义的隐含实体？
• 关系事实是否与实际代码关系相符？

整理优化机会：

• 能否将相近的重复事实合并为一条更清晰的事实？
• 能否将关于某个功能的微型事实（每个错误代码一条、每个分支一条）整合为一条描述该功能契约的事实？
• 超过约 80 条事实的文件是否应拆分为主题明确的文件，或进行精简？

验证质量：

• 手动维护的事实是否有待编写的、有意义的检查命令？
• 现有命令是否从外部测试行为，还是读取源文件或封装现有测试？

3. 与用户讨论

按严重程度组织你的发现：先讨论矛盾，再讨论缺漏，然后是含糊之处、复合事实，最后是术语不一致。对于每个问题：

1. 引用涉及的事实
2. 简洁说明问题
3. 提出具体的修复方案（改写、拆分、添加新事实或删除重复内容）
4. 等待用户决定后再进行修改

分批处理问题。不要一次性抛出 30 个问题；将相关问题分组，每次讨论几个。

4. 应用已同意的修改

用户批准修改后，立即应用。优化后的事实从 @draft 转为 @spec：

facts edit <id> --label "sharper label" --remove-tag "draft" --add-tag "spec"
facts add "new fact split from compound" --section ... --tags "spec"
facts remove <id>

将 @draft 事实拆分为多个精确事实时，删除原草稿，并将拆分后的内容作为 @spec 添加。确认每项修改都已正确落实后，再继续。

优化 @draft 领域事实时，实体采用 a <Name> is <definition> 格式，关系采用 a <Name> <verb>s <Name> 格式。拆分复合领域事实时，每个部分都应定义一个实体或一种关系。

5. 验证并总结

应用所有修改后：

facts check
facts lint

总结所做的更改：改写、拆分、添加或删除的事实，以及添加或修正的命令。说明仍需用户提供意见的问题，或尚未作出决定的问题。

指南

• 每项修改都需要用户同意。你提出方案，由用户决定。
• 优先明确表述，而不是删除。含糊的事实通常蕴含着一个亟待明确的精确事实。
• 拆分复合事实时，应通过拆分后的内容保留原意。
• 除非确实能验证相关主张，否则不要添加验证命令。明确的手动检查比错误的自动检查更好。
• 除非为解决实际问题所必需，否则不要重新组织章节或重命名。
• 优化 ## domain 之外的事实时，检查实体名称是否与领域部分（位于主 .facts 文件中）一致。对于术语不一致的事实，建议重命名。
• 保持对话聚焦。如果用户想添加全新事实（而不是优化现有事实），那属于 facts 技能的工作；不过，如果新 @spec 事实能够弥补你发现的缺漏，也可以提出建议。

示例对话

# Load
facts list
facts list --tags "draft"
facts check

# Present findings to user:
# 1. Vague: "d4e" says "handles auth correctly" — split into 3 precise facts?
# 2. Compound: "f6g" packs PostgreSQL + Redis into one fact — split?
# 3. Gap: no rate limiting fact in api/auth
# 4. Accumulation: 4 facts about webhook error codes — consolidate into one?

# User agrees — apply changes
facts remove d4e
facts add "rejects expired tokens with 401" --section api/auth --tags "spec"
facts add "refresh tokens extend session by 24h" --section api/auth --tags "spec"
facts add "login endpoint rate-limited to 10 attempts per minute" --section api/auth --tags "spec"
facts edit f6g --label "uses PostgreSQL for persistence" --remove-tag "draft" --add-tag "spec"

facts check
# Report: 2 @draft refined into 4 @spec, 1 gap filled, 4 webhook facts consolidated to 1