prd-to-goal

prd-to-goal — PRD → /goal 分解

将 PRD / issue / 规格说明转换为一行可直接复制粘贴的 /goal 命令。/goal 的难点不在于运行它，而在于编写一个收敛（会终止）、可证伪（可通过布尔值测试）且可观测（Agent 无需主观判断就能实际检查）的 until 子句。此技能可让这种分解过程变得可复现。

1. 何时使用

适用于以下情况：

• 你有一份书面 PRD、GitHub issue 或规格说明，并想据此运行 /goal。
• 过去的 /goal 运行出现偏离、循环，或因 until 子句含糊不清（until tests pass、until done、until design is good）而消耗了大量 token。
• 你需要说明中止预算的合理性——轮次、token、无进展阈值。

以下情况请勿使用：

• 一次性修复 bug，且失败的测试本身就是验收标准。直接运行 /goal until pnpm test -- auth.spec.ts passes。
• 没有书面 PRD。请先运行 write-prd——不能根据感觉进行分解。
• 工作具有破坏性或不可逆（数据库迁移、大量删除文件）。/goal 会重试；但你肯定不想对 DROP TABLE 重试。

2. 此技能接受的输入

输入	方式
粘贴的 PRD 文本	将其作为参数提供，或在调用后粘贴到聊天中。
GitHub issue	gh issue view <N> --json title,body,labels — 此技能会读取 body。
规格说明文件	Markdown / 文本文件的路径；此技能会 Read 该文件。
ADR / 设计文档	与规格说明文件相同。

3. 分解算法

1. 提取验收标准。 找出所有 MUST、SHOULD、Definition of Done、Acceptance Criteria 和复选框形式的条目。如果文档中没有这些内容，就停止并告知用户先运行 write-prd——没有可供收敛的目标。

2. 将每项标准映射为可观测的布尔值。 每项标准都必须归结为一个可通过 shell 检查的断言。可观测状态示例：

   • test -f path/to/file（文件存在）
   • pnpm test -- pattern passes（测试命令以 0 退出）
   • gh pr view <N> --json state | jq -r .state == "MERGED"
   • wc -l < src/auth.ts 返回的数字在限定范围内
   • pnpm lint 以 0 退出
   • curl -sf $URL 返回 2xx

3. 拒绝不可观测的标准。 删除或改写依赖主观判断的标准（代码很整洁、设计感觉合适、用户很满意）。要么找到一个代理指标（lint 以 0 退出、Lighthouse 分数 > 90、NPS 调查 ID 存在），要么将该标准告知用户，说明它不在 /goal 的适用范围内。

4. 组合 until 子句。 按优先级用 AND 连接可观测断言——将成本最低、最可能失败的检查放在最前面，这样循环会尽早短路。三到五项断言最合适；超过七项通常说明这其实是两份 PRD。

5. 将预算纳入同一条件。 Claude Code 每个会话只接受一个目标，后续设置会替换之前的目标；限额应写在这一个条件中（…, or stop after 15 turns）。这不是第二条命令。合理的轮次上限：

   • 单个功能为 15，重构为 30，bug 修复为 5。

   绝不要输出第二行 /goal。 第二行不会增加一道护栏——它会被解析为新的条件，替换第一行，导致会话只以预算为目标，所有验收断言都会被丢弃。此技能过去使用的 abort-if 形式根本不是 Claude Code 语法：对 2.1.226 二进制文件运行 grep -c -a -F 'abort-if'，结果为 0；它也未出现在 357 份存档变更日志中的任何一份。已于 2026-08-08 验证（#3312）。

4. 输出模板

此技能只输出一行，可直接粘贴：

/goal until <assertion_1> AND <assertion_2> AND <assertion_3>, or stop after <N> turns

先单独输出这一行。用围栏代码块包住也可以，方便用户复制。任何说明（断言顺序、grep 无法证明的内容）都放在这一行之后，并保持简短。绝不要输出第二行 /goal；如果输入中没有可观测的验收标准（算法第 1 步），则完全不要输出 goal 行：应说明原因，并建议改用 write-prd。

可选：生成评分量表（.claude/rubric.json）

如果用户希望获得超出通过／未通过布尔值的评分反馈，该技能也可以生成符合 ork-rubric/1.0 的 .claude/rubric.json（架构：${CLAUDE_PLUGIN_ROOT}/shared/rubric.schema.json），将每项验收标准映射到一个维度：

{
  "rubric": "ork-rubric/1.0",
  "skill": "prd-to-goal",
  "dimensions": [
    { "name": "regression_test_added", "weight": 0.4, "min_pass": 8, "min_blocker": 3 },
    { "name": "auth_suite_green",      "weight": 0.4, "min_pass": 10, "min_blocker": 5 },
    { "name": "lint_clean",            "weight": 0.2, "min_pass": 10, "min_blocker": 0 }
  ]
}

分数为 0–10（min_pass = 软性下限，min_blocker = 无论综合分数如何都必须满足的硬性阻断线）；维度权重之和必须为 1.0——完整规范见架构。

该文件特意设计为用户可在运行 /goal 前编辑——这正是其意义所在。调整权重和 min_pass 阈值，是用户在不重写断言的情况下将判断注入循环的方式（评分量表作为环境反馈，Lance Martin，2026-06-09）。超时后评分器（§8）会将评分量表（如存在）视为用户意图，其优先级高于字面断言文本。

5. 实例

示例 A — Bug 修复 PRD

输入（问题正文）：

Title: Login fails on emails containing "+"
Acceptance Criteria:
- New regression test in tests/auth/test_login.py covers email with "+"
- The new test passes
- All existing auth tests still pass

输出：

/goal until test -f tests/auth/test_login.py AND pnpm test -- tests/auth/test_login.py passes AND pnpm test -- tests/auth passes, or stop after 5 turns

理由：检查文件是否存在是成本最低的检查；针对性测试是回归门槛；范围更广的身份验证测试套件可捕捉附带影响。

示例 B — 功能 PRD

输入（PRD 摘录）：

Feature: User Avatar Endpoint
MUST:
- New route GET /users/:id/avatar registered
- Returns 200 with { url: string, updatedAt: ISO8601 } for known user
- Returns 404 for unknown user
- Integration test covers both cases
- OpenAPI spec updated

输出：

/goal until grep -q "users/:id/avatar" src/routes/users.ts AND pnpm test -- tests/integration/users.avatar.spec.ts passes AND grep -q "/users/{id}/avatar" openapi.yaml AND pnpm lint passes, or stop after 15 turns

理由：路由 grep 可发现已编写但从未接入的处理程序；集成规范同时涵盖 200 和 404；OpenAPI grep 确保文档要求得到落实；lint 可避免只完成一半类型标注的代码发布。

示例 C — 重构 PRD

输入（PRD 摘录）：

Refactor: split monolithic src/auth.ts (1842 LOC) into per-strategy files
Definition of Done:
- src/auth.ts under 200 LOC
- New files in src/auth/strategies/*.ts cover oauth, jwt, password
- All auth tests still pass
- Lint clean
- No new files outside src/auth/

输出：

/goal until [ $(wc -l < src/auth.ts) -lt 200 ] AND test -f src/auth/strategies/oauth.ts AND test -f src/auth/strategies/jwt.ts AND test -f src/auth/strategies/password.ts AND pnpm test -- tests/auth passes AND pnpm lint passes, or stop after 30 turns

理由：LOC 上限是收敛信号——没有它，/goal 就可能永远持续“改进”。文件存在性检查可固定结构拆分；测试和 lint 可确保正确性。预算更高，因为重构比 Bug 修复耗时更长。

6. 配方库 — 预构建循环

§3–5 会根据规范生成自定义的 /goal 命令行，而配方库则为反复出现的自主循环提供现成命令。每个配方都是围绕 ork 工作器技能构建的循环模式，遵循与生成命令相同的收敛、可证伪和预算规则。

配方	适用场景	工作器
🧪 覆盖率提升	有意义地将覆盖率提高到目标值	cover
🔴 生产环境错误清理	清除一批可处理的待办错误	fix-issue
📚 文档偏差清理	文档／参考资料与代码不一致	audit-full
⚡ 页面加载预算	页面超出延迟预算	performance
🧹 仓库清理	积累了过时的记忆／状态	dream
✅ 质量连胜	不要只相信一次绿色结果（测试套件不稳定）	verify
🎫 工单 → 可提交 PR	推进问题，直至 PR 通过 CI	fix-issue → create-pr
🧼 类型／lint 清零	清除类型／lint 待办项，且不使用抑制规则	修复器 Agent

完整配方——每条精确的单行 /goal until …, or stop after N turns 命令、收敛信号以及每个配方的防护措施：references/recipe-library.md。该文件是仓库内的源文件，计划用于 skills.sh 上的 ork-loops 套件（尚未构建；该渠道由 Forward Future 的 Loop Library 使用），这样循环配方可以独立传播，而 ork 提供每轮运行所需的机制。

7. 反模式

不佳写法	失败原因	良好写法
/goal until tests pass	哪些测试？已有的还是新增的？通过什么命令运行？Agent 可以挑选任何已通过的子集，然后宣称完成。	/goal until pnpm test -- tests/auth/test_login.py passes AND pnpm test -- tests/auth passes
/goal until the code looks clean	无法证伪。Agent 无法检查“看起来干净”——它要么会立即宣布成功，要么永远不会。	/goal until pnpm lint passes AND [ $(wc -l < src/auth.ts) -lt 200 ]
/goal until done	没有边界。不存在终止条件；若再加上宽松的 , or stop after 50 turns，运行就会在一夜之间消耗 500K 个令牌。	选择 3–5 个可观察的断言。如果做不到，说明 PRD 尚未准备好——请转到 write-prd。

8. 超时后的断言评估器

如果 /goal 循环达到回合上限，请勿重试同一行，也不要让循环中的 Agent 评判自己的断言。应启动一个全新上下文的评估器，审查断言集本身：

# Bare-eval pattern — independent context window, zero shared state:
Bash("CLAUDE_CODE_FORK_SUBAGENT=1 claude -p --bare \"$(cat /tmp/grader-prompt.txt)\"")
# or: Agent(subagent_type="general-purpose", prompt=grader_prompt)  # fresh spawn, no producer prose

评估器会收到 /goal 行、.claude/rubric.json（如果已生成）、最近 N 个回合的压缩摘要，以及重新生成的仓库状态证据。它会返回以下一种判定：

判定	诊断	操作
tighten	断言过于宽松——Agent 无需真正成功也能满足断言	使用更严格的修订行重新运行
loosen	按当前写法无法满足断言（路径错误、边界不可能达到、测试套件原本就已损坏）	使用可实现的修订行重新运行
abort	任务确实受阻（缺少访问权限、规格矛盾、环境损坏）	停止；向用户说明阻碍因素

评估必须在独立的上下文窗口中进行——绝不可自我评判（验证器子 Agent 的表现优于自我评判，因为评估器与执行者不共享上下文；Lance Martin，2026-06-09）。预算：每次超时调用一次评估器，且评估器绝不循环调用自身。

完整模式（提示词模板、独立性规则、示例）：${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/assertion-grader.md。

9. 相关技能

• ork:write-prd — 如果输入中没有验收标准，请先运行此技能。
• ork:brainstorm — 如果 PRD 本身存在争议，且你希望在编写目标之前先了解不同选项，此技能很有用。
• ork:audit-full — /goal 退出后，运行 audit-full 确认断言端到端确实成立（循环会信任布尔值；审计会重新检查意图）。