gvozdb/semantic-spec-writer-skill

语义规格编写器 (Semantic Spec Writer)

生成 .plan.ctx 和 .spec.ctx 文件，使得其他实现代理无需加载本技能即可直接使用。

模式

• 新文档：根据请求和已确认的仓库事实，直接编写最终的语义制品。不要先创建散文草稿。
• 现有文档：仅按请求进行转换，保留源语意和标识符。最终制品必须比源文档更短。
• 交接或重复使用：优化为可由其他代理或后续会话独立执行。
• 仓库执行包：当用户需要编码交接且代码库可用时，请阅读 references/execution-packets.md。在编写执行包之前，先确定一个最小的读取/编辑路径。

不要声称转换能为一次性实现节省总令牌数。转换增加了一个编写步骤；其经济性来自于更小的可重用上下文和更少的实现歧义。

目标

优化整个实现循环，而不仅仅是字符数：

• 保留每一个行为、约束、边界情况和确切的标识符；
• 移除叙述、重复、装饰性元数据和通用建议；
• 展示从需求到编辑再到验证的最短可靠路径；
• 优先使用直接语言，而不是需要解释的简写。

更小的文件只有在能保持更快且正确地执行时才有用。转换现有文档时，在编写前规划紧凑的结构，避免扩展源文档。不要为了追求文件大小而添加工具循环或重复重写。

令牌纪律

• 每个提供的源文档只读取一次，除非缺少某个事实需要针对性查找。
• 只检查确定范围、接口和验证所需的文件。
• 只编写一个最终成品。在初始编写时就使其更短。对于转换，从本技能目录运行一次 scripts/check_conversion.py SOURCE OUTPUT。当目标分词器已知且 tiktoken 可用时，传入 --encoding NAME。如果检查失败，移除一次冗余后再运行一次；切勿陷入无限的大小追逐循环。除非被要求，否则不要输出大纲、草稿、转换说明、大小报告或解释。
• 不要复制实现代理无需搜索即可从确切目标文件中获取的仓库事实。包含能够防止错误编辑或额外发现的事实。
• 优先使用确切的路径和一个可运行的验证命令，而不是通用的实现建议。
• 对于执行包，只将编写精力用于消除下游发现或防止错误编辑的事实。不要将执行包变成仓库转储。
• 赋予执行包一个规范的、有界的下游循环，该循环来自参考：一次有导向的读取、一次实现传递、一次声明的验证，然后在成功后停止。扩展需要具体的矛盾或失败。

格式

• 以纯文本 plan 或 spec 开头。
• 计划使用 .plan.ctx，规格使用 .spec.ctx，除非项目有其他约定。
• 使用明显的本地块名称。它们是标签，不是预留的关键字。
• 只包含承载信息的块。不要输出空节。
• 当目标、范围和合约事实在分离的块中会重复相同信息时，合并它们。
• 精确保留文件路径、符号、API 路由、字段、表格、环境变量、命令、状态、角色和错误文本。
• 精确保留字段所有权和嵌套。字段表示法要与实现语言匹配：对于 Python 的 JSON/映射，使用 event["payment_id"]，而不是 event.payment_id。永远不要发明源文档未定义的 data、payload 或其他包装器。
• 将 .ctx 视为纯文本，而不是 Markdown。不要将普通标识符包裹在反引号、粗体或其他展示标记中。仅对 verify 下的可运行命令使用反引号。
• 仅当能真正消除重复时才定义本地术语。首选描述性术语；避免单字母别名和发明记号。
• 仅当其他项引用它们时才添加 ID。
• 使用熟悉的表达式，如 x=true、x in [a,b] 和 condition -> result。不要依赖隐藏的语法。
• 只有当结构化字段会丢失关键细微差别时，才使用简短的 # 注释。
• 将并行的验证、输出字段和精确错误放在一个紧凑的映射中，而不是重复相同的句子框架。
• 在字段所有权确定后，在验证和错误映射中使用简短明确的标签，而不是重复完整的拥有者路径。
• 在错误映射中，让块承载重复的语法。优先使用 field: condition | ErrorType "exact message" 而不是对每一行重复 invalid owner.field -> ErrorType。
• 每行保留一个可独立测试的规则。当语法一致时，共享的映射可以容纳相关的字段情况。
• 在 acceptance 下，A* ID 只能使用一次。不要重复使用验收 ID 作为规则或任务 ID。

依据信息 (Grounding)

当代码库可用时，在编写前先进行检查。捕获已知的编辑范围、现有接口、约束和可运行的验证命令。仅包含用于确切的命令或现有命名检查的 verify；不要发明验证场景。不要猜测文件名或架构。

未知决策属于 open_questions。当没有未知项时，省略该块。

信息顺序

按照实现代理需要的顺序放置信息。仅使用相关的部分：

1. 目标或目的，包括已知的精确编辑范围；
2. 目标未声明的合约；
3. 规则、不变量、状态或流程；
4. 仅在依赖关系重要时的有序工作；
5. 验证命令和可观察的验收标准；
6. 未解决的问题。

精确的范围和验证通常比激进的压缩节省更多代理工作。

压缩规则

• 每个事实只陈述一次。
• 合并重复的需求。
• 当块的内容已被另一行承载时，省略该块。
• 验收引用应引用现有的规则、合约和验证 ID，而不是重述其散文。
• 当被引用的块已经陈述了可观察的行为时，验收仅保留为引用。
• 仅当原因改变实现决策时才保留原因。
• 用可观察的结果替换模糊的动词，如 improve、support、handle、optimize 和 fix。
• 保留罕见但有重要影响的边界情况。永远不要为使文件更短而丢弃它们。
• 不要仅仅为了减少字数而将普通需求编码为公式。
• 当精确的、源自源的整数公式比冗长的散文描述更容易正确执行时，优先使用公式。

示例

实现规格：

spec
target: [src/payments.ts,tests/payments.test.ts] :: 通过 Idempotency-Key 使 POST /payments 幂等
保留: 响应模式、认证行为

rules:
  R1: 密钥作用域是 user_id
  R2: 相同用户 + 相同密钥 + 相同请求体 -> 返回原始状态和请求体
  R3: 在返回成功前持久化结果

errors:
  E1: 缺少 Idempotency-Key -> 400 idempotency_key_required
  E2: 相同密钥 + 不同请求体 -> 409 idempotency_conflict

verify:
  V1: `pnpm test tests/payments.test.ts`

acceptance:
  A1: R1,R2,R3,E1,E2 -> V1

并行验证映射：

validation:
  retries: int>=0 | ValueError "重试次数必须为非负数"
  timeout: int>0 | ValueError "超时时间必须为正数"

实施计划：

plan
goal: 将会话存储从内存迁移到 Redis，不改变 API 行为

facts:
  当前存储: src/session/memory.ts
  合约测试: tests/session.contract.test.ts

tasks:
  T1: 在现有 SessionStore 接口后添加 Redis 适配器
  T2: 对内存和 Redis 适配器运行合约测试
  T3: 在 T2 通过后切换组合根节点

verify:
  V1: `pnpm test tests/session.contract.test.ts`

质量门控

在完成前，验证：

• 一个新的实现代理可以在没有本技能或未声明上下文的情况下行动；
• 每一行都改变了范围、行为、实现顺序或验证；
• 没有需求被重复或被未定义的缩写替代；
• 已知的文件、接口和命令是确切的；
• 验收标准是可观察的并能追溯到声明的合约；
• 每个字段仍然与源文档中的拥有者和嵌套保持一致；
• 结果更短是因为去除了冗余，而不是因为掩盖了含义。

先输出语义文档。仅当有未解决的决策会实际阻碍实现时，才附加单独的说明。