| name | requirements-gate |
| description | 需求门禁（Requirements Gate）——在写任何代码之前，把模糊的开发需求变成一份无歧义、可验证的 spec.md。只要用户提出新的开发需求或变更请求（实现 / 新增 / 开发 / 加一个 / 修改 / 重构 / 优化 / 接入 / 修复 / add / implement / build / feature / fix），哪怕措辞很随意，且该任务还没有 status: approved 的 spec.md，就必须使用本技能。当 UserPromptSubmit hook 注入「需求门禁」提醒时也必须使用。不要因为需求看起来很简单而跳过——简单需求走 L1 轻量路径，同样留档。 |
需求门禁 Requirements Gate
为什么存在
你评审的不是一段文案，而是一个待执行的决策提案。绝大多数返工不是代码写错，而是需求本身有歧义、缺上下文、假设未声明。把这些问题在写代码之前暴露，成本是几分钟；在写代码之后暴露，成本是几天。
三条核心原则（违背任何一条，门禁就退化成普通的"PRD 润色 prompt"）：
- 先补上下文，再评审。 没有检索过仓库和历史记录就给的建议，只是听起来正确的通用 PM 话术。每条判断必须标注是
[证据]（附文件路径/出处）还是 [推测]。
- 不给最终判决。 永远不输出"通过/不通过"或"8/10 分"，只输出 readiness 等级、缺口、风险和需要人类决策的问题。最终拍板的是用户。
- spec.md 是契约，不是记录。 后续会有独立 subAgent 拿 spec.md 核对实现是否"不重不漏不偏不倚不多不少"。验收标准编号必须稳定、每条独立可测、非目标必须明确——否则契约无法机械核对。
门禁分级
先分类，再决定评审强度。分类本身花 10 秒，但决定了后面是 2 分钟还是 20 分钟：
| 级别 | 适用 | 动作 |
|---|
| L0 跳过 | 非开发请求（提问、讨论、运维操作）；已有 approved spec.md 的任务延续；用户显式标注 [skip-gate] / [跳过门禁] | 忽略门禁，正常响应 |
| L1 轻量 | 琐碎修复：typo、改文案、单行 bug、配置调整 | 简版 spec.md（一句话需求 + 1–2 条 AC），不提澄清问题，2 分钟内完成 |
| L2 标准 | 常规新功能 / 功能变更 | 完整流程（下方 Step 1–7） |
| L3 深度 | 触碰任意一项：数据契约 / 权限模型 / 计费定价 / 对外 API / 不可逆迁移 / 跨团队指标 | 完整流程 + 强制依赖影响面分析 + 多角色评审（见 references/review-dimensions.md） |
拿不准 L1 还是 L2 时取高不取低。
流程
Step 1 — 上下文收集（检索先于评审）
评审一份脱离上下文的需求是不可能的。先检索，优先用 rga：
- 仓库内相关模块、接口、配置（关键词来自需求本身）
specs/ 及 brainstorming 输出目录下的历史 spec.md：是否有重复、冲突或可复用的结论- CLAUDE.md / docs / spec：既有约定与原则
把找到的证据（文件路径 + 一句话结论）记下来，写入 spec.md 第 7 节。检索结果为空也是信息——说明这是全新领域，假设风险更高。
Step 2 — 模糊性清除
读 references/ambiguity-checklist.md，扫描需求原文中的模糊表达（"体验好一点"、"优化"、"支持更多场景"……）。对每一处输出四件套：模糊类型 → 执行风险 → 澄清问题 → 可直接替换进 spec.md 的改写。
只说"这里不清楚"是失职；给出可替换文本才算完成。
Step 3 — 缺口扫描
- NFR：按
references/nfr-checklist.md 过一遍，PM 最容易漏的恰是上线后代价最高的（回滚、降级、隐私、可观测性）。不适用的维度写 "N/A + 原因"，不许留空。
- 依赖与影响面：这个改动依赖哪些系统/接口/数据契约？影响哪些模块、指标、相邻功能？与 Step 1 检索到的历史结论是否冲突？是否重复已有 roadmap 项？
Step 4 — 清晰度判定与路由
Step 2/3 扫描完成后，按缺口性质路由，这是门禁最关键的一次判断：
| 缺口性质 | 特征 | 路由 |
|---|
| 方案级未知 | 目标本身不明确、存在多个可选方向、用户自己也还没想清楚要什么 | 交棒 superpowers 的 brainstorming 技能做梳理，由它产出 spec.md |
| 参数级缺口 | 方向明确，只缺上限 / 默认值 / 边界取舍 | 门禁直接澄清：一轮最多 5 个选项题，能用合理默认值兜底的不问 |
交棒 brainstorming 不是简单转手——把 Step 1 的检索证据（文件路径 + 结论）、Step 2 的模糊点四件套、Step 3 的缺口清单一并作为输入带过去。带着证据进 brainstorming 和空手进，产出质量差一个量级；这份前置扫描就是门禁对 brainstorming 的增值。
用户跳过的澄清问题：采用显式默认值 + 写入 spec.md「待确认」，绝不静默假设。
Step 5 — 产出 / 验收 spec.md
spec.md 是统一契约文件。两条来路，一个出口标准：
- brainstorming 产出：拿回 spec.md 后按
assets/spec-template.md 核对结构，补全缺失章节——常见缺口是 AC 编号、非目标、NFR 表、待确认表、frontmatter 的 status/level。补全是门禁的职责，不要退回 brainstorming 返工：它负责把需求想清楚，门禁负责让契约可机械核对。
- 门禁自产（需求本就清晰，无需 brainstorming）：直接按模板撰写。
存放位置：跟随 brainstorming 的输出位置约定；门禁自产时沿用同一约定；皆无约定时默认 specs/<YYYYMMDD>-<slug>/spec.md。初始 status: clarifying，frontmatter 的 source 记录来路（gate / brainstorming）。
验收标准（AC）规则：
- 每条格式：当 {前置条件}，执行 {操作}，应 {可观察结果} ——不可观察的不是 AC，是愿望
- 编号 AC-1、AC-2… 一旦发出不复用不重排，删除的标记为
[已废弃]
- AC 覆盖范围 = 第 3 节范围；第 4 节非目标用于判"不多"
Step 6 — 门禁判定
向用户输出（保持简洁，一屏内）：
- Readiness 等级：
草稿 / 待澄清 / 可开发（定义见 references/review-dimensions.md）
- 最优先的 3–5 个缺口（按风险排序，每条附
[证据]/[推测] 标注）
- 需要人类拍板的问题
用户确认后将 status 改为 approved。approved 之前不写任何实现代码。
Step 7 — 交棒
- 进入开发：接 superpowers 的 writing-plans（或 spec-kit
/plan），并把 spec.md 路径写进开发计划首行
- 开发完成后：用户会触发独立验证 subAgent，以 spec.md 的 AC 列表与非目标为基准核对实现（该环节另有技能，本技能只负责留好契约）
Rationalizations — 想抄近道时读这里
| 借口 | 纠正 |
|---|
| "这需求很简单，不用走门禁" | 简单 → L1，2 分钟留档，不是跳过。"简单"本身就是一个未验证的假设 |
| "用户很急" | 越急越容易返工。急 → 问题问得更少、默认值给得更果断，而不是不问 |
| "可以边写代码边澄清" | 代码会固化错误假设；改代码比改文档贵一个数量级 |
| "我理解用户的意思了" | 理解 ≠ 共识。写下来被用户确认过的才是共识 |
| "上下文已经够了" | 没有 rga 检索记录就是不够。证据 = 文件路径，不是感觉 |
| "需求不清晰，我先替用户猜个方案写下来" | 方案级未知交棒 brainstorming，门禁不替用户发明需求 |
| "给个评分让用户参考" | 评分无信息量。要的是缺口、证据、可替换文本 |
| "用户没回澄清问题，先做了再说" | 显式默认值 + 写入待确认，让假设可见、可推翻 |
Verification — status 改为 approved 前自检
安装与 hook 注册说明见同目录 INSTALL.md（面向人类读者，不属于技能上下文）。
