规格定义

这个技能解决什么问题

在需求分析阶段，团队会产生大量决策记录和交接包，但这些决策往往停留在分析文档里，没有被物化成可执行的规范文档。同时，规格编写过程中容易出现几个典型问题：规范对象（如 CAP、PAGE、VIEW）没有来源追踪，无法追溯每个决策的原始依据；原型设计稿里的视觉细节和 mock 数据污染业务规格，导致规范文档混杂了实现层面的噪声；多个功能（feature）的规范文件互相覆盖，缺少隔离机制。

核心能力与关键步骤

这个技能的核心工作是把经过人工确认的决策事件，按规范结构写入 spec.md 及相关产物。

输入门禁阶段，技能会读取 analysis-handoff.json 和 requirements-analysis.md，校验交接包的 admission_status。只有状态为 user-confirmed 的概念才能创建规范对象（如 CAP、G/US/FR、ENTITY 等），助手建议和业务推导必须经过人工明确确认。

进入编写流程后，技能按以下步骤执行：

• 通过 scripts/resolve_workflow.py 定位唯一的 PROJECT_ROOT 和 FEATURE_DIR，避免覆盖其他 feature
• 根据证据判断当前是 Greenfield、Incremental 还是 Revision 场景
• 先建立来源到规范对象的追踪关系，再编写正文
• 按业务能力 → 用户 → 流程 → 规则 → 实体 → 验收 → UX 的顺序定义，不自动添加企业常见能力
• 明确区分信息架构对象：CAP 是独立能力，PAGE 是稳定路由页面，VIEW 是上下文视图，ACT 是业务操作
• 生成 spec.md、需求检查清单、.specify/feature.json、requirements-source.json 和 information-architecture.json
• 字段密集型需求额外生成 field-contract.json，并在 spec.md 写入 FIELD-* 摘要
• 最后运行 scripts/validate_delivery_contract.py --stage specify，退出码 0 且 valid: true 才算交付成功

内容路由门禁会过滤掉非规范性输入：原型布局、颜色、间距等视觉信息只写入 Prototype visual plan；mock 数据和示例用户只写入 Prototype fixture；截图和评审记录只写入 Evidence。如果发现这些内容被表述成业务规则，技能会停止写回并输出 SPEC_CONTEXT_CONTAMINATION。

适用边界与注意点

这个技能不自动调用 Prototype，完成 Specify 后交给 Clarify 处理。它也不修改 Frozen spec，Revision 场景必须先执行 version 的修订操作。

版本上下文方面，技能会读取 version-context-contract.md，解析 Product-ID、Product-Version、Spec-Revision 和 Feature-ID。新 Draft 可以从 Spec-Revision: r0.1.0 开始，但必须声明目标产品版本，否则返回 PRODUCT_VERSION_REQUIRED。

工作区管理上，一次性脚本和中间产物统一放在 .specify/work/specify/ 下，正式文件只保留契约规定的根目录文件和 .specify/ 状态文件。失败记录保留在对应 run manifest，由 speckit-workspace 负责后续归档。