prd — 一句诉求 → 可验证的契约五字段

/prd 把一句诉求变成工作状态的契约五个字段：goal / acceptance / invariants / unknowns / human_checkpoint。

工作状态、证据层、三个 profile 的边界、产物落点见 ../loop-it/CONTRACT.md——本文件不复述。 这里只写三件事：何时调用、产物长什么样、失败怎么办。

何时调用

• 用户给了一句诉求，落地方案还要自己定（「怎么落地你定」「文件格式你定」）——就是这里，别直接开写。
• 需求还没成形：写不出可证伪的验收条件，或作用域边界还没划。
• 「装得进一个上下文」不等于「定义好了」（CONTRACT §3）。小不是跳过规划的理由；反之，已经有人写好了验收条件（一条 issue 卡、spec 里的一项）就不需要 PRD，直接进 /loop-it。

输入

一句诉求 + 仓库上下文：AGENTS.md 的路由表、相邻代码、既有约定。能自己读到的就自己读，别拿它当澄清问题问回去。

输出

一份短文档，落在 <scope>/documents/prd-<feature>.md（作用域根见 CONTRACT §8；目录不存在就 mkdir -p）：

• 没有远端 / gh 没登录时，这份文档就是契约的载体。
• 有 gh 且人指定了 issue 时，直接写进那条 issue 正文——同一套字段，换个载体。

只写契约五字段。 谁受益、为什么现在做由 goal 承载，不必另起一节背景。简介 / 用户故事 / 功能需求 / 成功指标 / 技术考量都是按需的：有真实内容就写，没有就不写。长度由未知量决定，不由模板决定——九节结构不进默认路径。

acceptance 的判断：

• 「工作正常」「体验良好」不是验收条件。可观测的 UI 状态 / API 响应、清晰的输入输出对、能跑的工具检查才算。
• 按「能不能被同一次观测证明」合并，不按功能点逐条列。 想少写测试，杠杆是减少验收条件的条数（CONTRACT §4）。
• 有界面时，外观是一等验收条件——写进 acceptance（附视觉验证），不要划进非目标：把「好看」划出去，等于允许交付一个能用但没法看的东西。
• 每条要哪一层证据（L1–L4）执行时才标，不写进文档（CONTRACT §4）。

unknowns 是一等公民，不许静默猜： 每条只有两种归宿——有人认领，或显式写下「我按 X 假设推进」（[Assumption]）。Open questions: None 是最危险的一行，它通常是没想，不是没有。

一份填好的短 PRD 与带字母选项的提问格式见 references/example.md。

澄清

只问真正阻塞的：不回答就写不出可验证的 acceptance，或者答案会改变作用域边界。其余一律合理默认值 + [Assumption]。

• 用 ask_user_question，不要用散文把回合停在「等你回复」上——DSH 里 turn_end: completed 就是这个回合的终点。
• 问题带字母选项，人可以回「1A 2C」；数量随歧义伸缩，不凑条数。
• 能问到人时就在能问到人的上下文里做：子代理发起的 ask_user_question 会被拒，所以别把这个技能派给子代理。
• 为什么不设评审闸门： PRD 是活文档，不是批准件；审批闸门把澄清切成瀑布。要评审就由 /review-it 派不共享上下文的子代理做，人只在 human_checkpoint 被叫一次（CONTRACT §5）。

边界

• 不做实现。 只产出契约；落盘即视为可用，不等「回复 OK」。
• 不做第二份真相。 文档与工作状态冲突时以工作状态为准（CONTRACT §1）；能只从状态 + issue 正文 + 代码推出来的东西，不用写。
• 不把「建议下一步」当产出：落盘后跑一次 route（见下），照它打印的 next: 加载下一个技能。
• 只在两种情况停：人明确说了「等评审过了再往下」，或「我只要文档」。

失败怎么办

停在「等你回复」上是唯一一定错的做法。 实测过一次：一条臂问了 4 个问题然后结束回合，30 秒后整个运行到此为止，PRD、issue 卡一个都没产出。

往下

python3 <SKILL_DIR>/../loop-it/scripts/loop_state.py route --scope <scope>

（<SKILL_DIR> 是加载本技能时报告的 Base directory）

它按磁盘事实（documents/、issues/、检查点、工作树的改动）算出链上走到哪一段，next: 那一行就是你要用 skill 工具加载的技能名。照它说的加载——「我判断这整件事装得进一个上下文」 这句话属于被加载的那个技能，不属于这里。

链上的位置不靠回忆：那句话在你读完本技能二十多次调用之后就不在手边了，而 route 随时可查。 它还会拦越序——规划阶段却已经有实现改动时直接报错退出（踩过一次：PRD 落盘后直接开写代码， 整条链一步没走，直到用户当面追问才回头）。

用户后来的反馈一律当修订，不用回头重走。