specsfy-03-specify

装配单一规范

强制准备

执行此技能前，必须在项目根目录加载 $specsfy-setup。自动交接时，请在此步骤前重新加载。复用对话中已确认的根目录；如果 setup 指出有待处理事项，请勿继续。

交互模式

交互模式：perguntas。 提出任何问题前，请阅读并应用 .specsfy/Spec.md 中的 Contrato de perguntas numeradas。

创建或更新 specs/draft/<NNNN>-<slug>/ 包，其中 spec.md 是整个 SDD 流程唯一的规范性来源。只有目录使用编号；文件始终保持为 spec.md。将发现、研究、澄清、产品、技术计划、数据模型、契约、TDD、BDD、验证、任务、决策和结论整合到三个明确的阶段中。外部参考资料放在 research/ 中；不要生成 plan.md、research.md、data-model.md、tasks.md、检查清单或第二份规范。

整合 Laravel 规范前，请阅读 .specsfy/PACKAGES.md、 docs/packages/README.md 和 docs/packages/ 中的说明文件。如果请求中包含 GitHub 包 URL，或依赖 Composer 库，请加载 $specsfy-specialist-laravel-package-manager，以确认该包是否已存在，并记录需求，避免重复添加依赖。

协调对话

完成此步骤或发现其他步骤的工作时，请通知 Pendência detectada: <descrição> — ação: resolvendo nesta etapa，并在属于当前范围时解决。如果需要移交责任，请通知 Transição automática: $specsfy-03-specify → $<destino> — motivo: <motivo> — resultado esperado: <resultado>，并立即加载目标技能，无需征求确认或重复命令。在同一对话中继续。完成当前步骤所需的修正后，请通知 Retomada automática: $<destino> → $specsfy-03-specify — pendência resolvida: <resultado>，并立即恢复当前步骤。每次交接后重新评估状态，以避免循环。无需征求交接确认；敏感操作仍需获得明确授权。

准备

1. 根据用户提供的目录确定项目根目录；如果用户未提供其他目录，则使用 Path.cwd()。不要搜索或将目标目录提升为 Git 根目录。
2. 创建规范时，解析此技能的目录，并在写入前执行：

node <diretório-da-skill>/scripts/iniciar_spec.mjs \
  --title "<nome da especificação>" [--slug <slug>] [--root <raiz>]

3. 使用脚本打印的绝对路径。脚本会分配下一个本地 ID，优先使用 .specsfy/templates/custom/Spec.md，其次使用受管模板 .specsfy/templates/Spec.md，并且只创建 specs/draft/<NNNN>-<slug>/spec.md；绝不要将文件重命名为包含 ID 的形式。 在开发此仓库时，脚本会将 skills/templates/Spec.md 用作回退模板；在使用方项目中，如果缺少模板，则需要执行 specsfy install。
4. 更新规范时，使用当前根目录下提供或发现的现有规范路径；不要再次运行初始化程序。
5. 阅读 specs/inbox/ 中的来源记录、backlog 条目、backlog 细化说明、当前请求、该路径下的规范及其 research/，并阅读能够揭示实际限制的仓库文件。
6. 如果信息不足以确定问题、参与者和结果，请通知存在待处理事项，并加载 $specsfy-02-backlog 执行完整流程。流程结束后恢复此技能，并使用生成的完整或部分说明。
7. 收到需要细化的报告、故事、转录或规范时，请阅读 references/mcr-10.md。
8. 如果 .specsfy/DATABASE.md 存在，请阅读。当用户旅程依赖已保存的信息，而该文件未说明产品需要记住什么信息、由谁使用这些信息或这些信息何时不再需要时，请加载 $specsfy-data-discovery，并在记录确认后恢复此技能。

应用 MCR-10

1. 保留原始表述，并识别目的、参与者和结果。
2. 分析含义模糊的术语、术语等价关系和派生关系。
3. 将实质、数量、质量、关系、地点、时间、位置、所属、行动和受影响情况作为灵活的分析视角，而非问卷。
4. 将个人陈述与分析过程中产生的推断、假设、决策、冲突或待解决问题区分开。
5. 如果存在适用的缺口，加载 $specsfy-02-backlog，执行每个领域最多八个问题的周期，并在周期结束后返回此技能。如果个人选择 avançar，则应用中央契约中定义的确认和记录。若仍有适用事项，保留 Status: Draft 和 Definition Gate: Pending；不要将 spec 提升为 Defined，也不要在本次恢复时重新开启同一周期。
6. 将决策重新组合为包含主体、条件、行动和可观察效果的陈述；推导规则、用户故事、Gherkin、边界和故障。
7. 将结果记录在现有的 spec.md 章节中；不要单独生成 MCR 报告，也不要将参考内容复制到切片包中。

编写

• 始终保存到 <raiz>/specs/draft/<NNNN>-<slug>/spec.md；ID 属于目录，文件必须保持为 spec.md。
• 仅将实际查阅过的副本、快照、契约、schema、示例和来源说明存放在 <raiz>/specs/draft/<NNNN>-<slug>/research/。不要在该目录中放置生产代码、测试或规范性文档。
• 研究 API 或外部文档时，将允许保存的证据存入 research/，并在「已存储的研究成果」中列出路径、来源、版本／日期、许可证和影响。如果许可证或条款不允许复制，则存储元数据、URL、访问日期、可用时的校验和／版本以及自行撰写的说明，不得转载受保护的内容。
• 除 spec.md 和 research/ 外，不要在功能包中创建其他条目。
• 将 specs/backlog/<NNNN>-<slug>.md 提升为正式规范时，在规范中记录该路径，并将条目更新为 Status: Promoted，同时填写新建规范的路径。backlog 保留来源信息，但不再作为行为依据。
• 直接根据 specs/inbox/<data-hora>-<slug>.md 派生规范时，在规范中记录该路径，并原样保留捕获内容。初步分析仅作上下文，不是已确认的需求。
• 保留表头为两列 Markdown 表格，列名为 Campo 和 Valor；不要将元数据转换为 **Campo**: 值 行。
• 在表格中，将 ID 声明为 SPEC-NNNN，将 Slug 声明为 <NNNN>-<slug>，并确保 slug 与父目录一致。
• 严格保留已解析模板的三个阶段和 18 个章节： .specsfy/templates/custom/Spec.md（若存在），否则使用 .specsfy/templates/Spec.md。
• 精炼时替换模板中其余的编辑性内容；提升为 Defined 的规范中不得保留模板示例或占位符。
• 更新时编辑现有文件，并保留仍然有效的 ID 和决策。
• 为新增条目编号，不得复用或重新编号已删除的 ID：
  • 用户故事：US-001；
  • 功能需求：FR-001；
  • 非功能需求：NFR-001；
  • 验收场景：AC-001；
  • 决策：DEC-001。
• 将每项需求写成可验证的行为。
• 使用 Given/When/Then 编写每个场景，并将其关联到至少一项需求。
• 为整个功能以及每个 US、FR 和 NFR 至少定义三个不同的 AC。只有当 AC 在 **Cobre** 中声明 ID 时，才计入覆盖；通过顺畅路径、关键变化／规则以及实质性故障或限制来扩展上下文，避免重复等效场景。
• 在相关时纳入范围外事项、错误、限制、安全和无障碍要求。
• 当表头声明 Interface para pessoas: Sim 时，在第 10 节中依据技术栈和本地约定，填写模板规定的九个部分：屏幕、信息流、菜单和主要导航、表单和操作、组合方式、React 区块及 shadcn/ui/ReUI 组件、状态和无障碍要求。使用 INTERFACE.md、.specsfy/STACK.md、清单、屏幕和现有代码作为当前技术栈与系统的依据；记录哪些内容将保留、哪些将变更。未检查现有系统前，不得提出不兼容的库，也不得重构现有屏幕。 加载 $specsfy-specialist-ux-design、$specsfy-specialist-ui-design 和相应的界面技术栈专家。不能接受仅描述 API、数据库或服务的 CRUD 说明。 在 Laravel + React 项目中，明确记录 shadcn/ui 和 ReUI、所有计划采用的 React 区块、各自职责、文件、来源组件及复用规则。页面只负责组合这些区块。
• 没有界面时，声明 Interface para pessoas: Não，并说明交付内容为何不会由人在屏幕上使用。
• 技术章节应具体到足以编写包含文件路径的任务，同时不得混淆内部实现选择与用户结果。
• 在「假设」中记录可逆的默认选择；只有在合理选项会实质性改变范围、数据、安全、UX 或测试时，才请求澄清。
• 标记为 Defined 的文件中不得留有占位符、模板示例、TBD、TODO 或澄清标记。
• 后续任务保留在「14. 任务」章节；后续技能应更新同一章节，不得创建其他文件。
• 使用元数据 Definition Gate、Plan Gate 和 Delivery Gate 表示就绪状态，不得另建报告。

尊重已批准的规格

如果规格已获得 Definition Gate: Passed，而用户要求添加、 删除、修正或更改内容，请说明待处理事项，并自动加载 $specsfy-update-spec。此技能会对影响进行分类，更新规范来源， 并仅使受影响的 gate 失效。只有当此次更改使规格回到初始定义状态时， 才恢复使用此技能。

保留可追溯性

对于每个 FR 和 NFR，至少指出三个 AC 场景，并明确保留 NFR 的验证方法。对于每个故事，指出能够实现其价值的需求，并至少列出三个 AC。之后在 TDD 用例和第 14 节中使用相同的 ID。

管理 research

• 规划前，仅加载已编入索引的证据，并使用以下内容验证 claims：

node .agents/skills/specsfy-03-specify/scripts/load_research.mjs \
  specs/<estado>/<NNNN>-<slug>/spec.md

• 对于重要 research，在第 2 节记录 R-ID、重要性、claim、判定结果、 置信度、本地证据和预算。尚未验证的 critical claim 会阻止交接；被证伪的 claim 仍需保留记录。ID 必须唯一，支出不得超过上限，引用的 Markdown 锚点必须存在于本地文件中。

自我验证

文件处于 Draft 状态期间，执行中间结构验证：

node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs specs/<estado>/<NNNN>-<slug>/spec.md --allow-draft

最多用三个周期修正结构性问题。specsfy-04-validate 技能会进行语义审查、在第 13 节记录结果，并将状态升级为 Definition Gate: Passed 和 Status: Defined。在此之前，保持 Status: Draft、Definition Gate: Pending，并报告阻塞性决策。

报告

请提供：

• 路径 specs/<estado>/<NNNN>-<slug>/spec.md；
• 已存储的 research 路径，或声明没有外部来源；
• 状态；
• US、FR、NFR 和 AC 的数量；
• 重要假设；
• 自动转至 $specsfy-04-validate 的情况、原因和预期结果。

按需邀请专家

当需求、NFR、数据或技术决策需要专业知识时，请阅读 references/specialists.md。在规格中记录该需求，并建议加载相应专家。如果尚未安装该专家，请先征求明确授权，再进行安装。