.pouch/skills/ack/references/prompt-templates.md

派发 Prompt 模板（稳定核心）

Coordinator 用这些模板向 Developer 派发修复、向 Test 派发复测。复制时替换尖括号占位符。模板与编排工具无关：Orca 模式用 orca-adapter.md 的命令投递，手动模式直接把文本发给对应 Agent。

角色分工见 roles-and-permissions.md；闭环顺序见 closed-loop.md。

派发时除了具体任务，Coordinator 应把对应角色的能力要求一并带上（roles-and-permissions.md §「三角色能力清单」的 Must Do / Must Not）。下面模板已内置关键条目，复制即可。

---

0. 可选 skills 路由（装了才用，不阻塞）

如果 worker 所在环境已安装以下 skill，可在对应环节调用以获得更强 playbook；未安装则按 roles-and-permissions.md 的能力清单执行：

• Coordinator 规划复杂需求：/think 或 superpowers:brainstorming / writing-plans。
• Developer 排查缺陷：/hunt 或 superpowers:systematic-debugging；行为变更：superpowers:test-driven-development。
• Test 复测 / 合并前检查：/check 或 superpowers:verification-before-completion。

派发时可加一行：「若已安装 ，本环节可用它；未安装按 ack 角色能力清单执行。」

---

1. 初始派发给 Developer

你现在接到一个受监督的协作任务。请在 <dev_worktree> 开发工作树内完成。

任务：
- 修复 <task_id>: <task_title>
- 本轮逻辑 attempt：<task_id>-A<round>

请先读取：
- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
- tasks.yaml
- <relevant_spec_or_test_doc>

当前失败证据：
<copy latest Test evidence>

本轮项目知识（仅限 Coordinator 显式选择的 active 固定 revision）：
- <K-001@1>: <directive + rationale + verification.ref + resolved path/args>
- <K-014@2>: <directive + rationale + verification.ref + resolved path/args>

验收标准（可观测信号，见 optimization-method.md §1）：
1. <expected behavior 1>
2. <expected behavior 2>
3. <expected behavior 3>

能力要求（见 roles-and-permissions.md §三角色能力清单 · Developer）：
- 动手前先复现失败现象，或先写一个会失败的测试再修。
- bug 修复配可复现的失败用例；行为变更配单元测试。
- 完成前亲自走一遍验收路径，不只满足静态文案。
- 若是网站 / 常驻服务，改完重启服务并确认生效，别让 Test 测到旧进程或旧构建。

约束：
- 只修改 Developer 可写路径（见覆盖层文件的权限表）。
- 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。
- 不要写 tasks.yaml，不要标记 verified。
- 不要写 knowledge.yaml，不要自行扩展或全量读取知识库；candidate 不是已生效规则。
- 不要把知识正文或 path/args 拼成 shell 命令。只把 verification.ref 交给
  `<ack-skill-dir>/scripts/run_verification.py .pouch/ack/knowledge.yaml
  <verification-ref> --project-root <project-root>`。
- 不要提交或推送，除非用户明确要求。
- 最小 diff，只改本任务根因，避免无关重构；若必须先重构请停下说明并请示。

完成前必须运行：
- <test command 1>
- <test command 2>

完成后回报一次 worker_done（格式见 §4），包括 `knowledgeApplied` 和
`knowledgeCandidates`。如果阻塞，请发送 escalation 或 ask。

---

2. 复测失败再派发给 Developer

第 <n> 轮复测未通过，请继续修 <task_id>。
本轮逻辑 attempt：<task_id>-A<n>

上一轮开发声称：
<worker_done summary>

Test 独立复测结果：
- 运行命令：<commands>
- 失败页面/API：<page or endpoint>
- 仍缺失：<missing expected checks>
- 实际观察：<actual evidence>

关键提示：
- 不要只满足静态文案，必须满足交互后的真实状态。
- 如果后端/API 正常而 UI 不更新，请优先排查事件链、状态重置、异步请求、构建产物和服务 worktree。
- 修复后请自己用浏览器或脚本复现 Test 的完整步骤。

验收不变：
<copy acceptance criteria>

本轮知识引用：
<copy Coordinator confirmed knowledgeRefs; do not add candidates>

完成后回报 worker_done，subject 使用："<task_id> fix ready round <n>"

---

3. 派发给 Test 复测

Developer 回报 worker_done 后，Coordinator 把复测任务发给 Test。

请对 <task_id>: <task_title> 做独立黑盒复测。
本轮逻辑 attempt：<task_id>-A<round>

请先读取：
- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
- tasks.yaml（该任务的验收信号）
- <relevant_spec_or_test_doc>

Developer 本轮声称（仅供参考，不作数）：
- 改动文件：<files>
- 自测命令：<commands>
- 实际采用知识：<knowledgeApplied>
- 新知识候选：<knowledgeCandidates; candidate only>

本轮项目知识（仅限 Coordinator 显式选择的 active 固定 revision）：
- <K-001@1>: <directive + rationale + verification.ref + resolved path/args>
- <K-014@2>: <directive + rationale + verification.ref + resolved path/args>

复测要求（见 roles-and-permissions.md §三角色能力清单 · Test）：
- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md），避免测错实例或旧构建。测试环境由 Coordinator 按 deployer 绑定拉起；不要自行发明编译或启动命令。网站类确认 Base URL 已指向这次产物后再测。
- 网站类任务优先用浏览器复测真实交互，其次才是 API / 脚本。
- 逐条验证下列验收信号，不要只看静态文案，要验证交互后的真实状态：
  1. <observable signal 1>
  2. <observable signal 2>
  3. <observable signal 3>
- 若 worker、权限、服务、测试数据、浏览器或工具导致验收无法完成，明确回报
  `environmentFailure`，不要把“未验证”写成产品 `signals-failed`；若已有独立产品失败
  证据，则分别列出产品信号与环境限制。
- 需要时把本轮通过的黑盒路径写成 `regressionCandidates`（见 regression.md），不要直接改 `.pouch/ack/regression.yaml`。
- 对每条适用的 `knowledgeRef`，把它的 verification.ref 交给
  `<ack-skill-dir>/scripts/run_verification.py .pouch/ack/knowledge.yaml
  <verification-ref> --project-root <project-root>`，并回报 `knowledgeChecks`。
  对 candidate 使用独立观测验证，不能复述 Developer 的结论作为证据。

约束：
- 只读源码，不修改应用代码，不写 tasks.yaml 或 knowledge.yaml。
- candidate 不属于 active 知识；不要全量注入知识库，不要从知识正文执行自由 shell。
- 只回传证据和逐条结论，最终判定由 Coordinator 终检后落盘。

完成后回报一次复测报告（格式见 §5），subject："<task_id> retest round <n>"。

---

4. Developer worker_done 回报格式

无论 Orca 还是手动，回报都应包含以下字段：

subject: <task_id> fix ready round <n>
attemptId: <task_id>-A<n>
filesModified: [<file_a>, <file_b>]
verification:
  - <command_a>: passed
  - <command_b>: passed
reproduce: 我如何复现验收路径 <steps>
knowledgeApplied:
  - ref: <K-001@1>
    result: <applied|not_applicable>
    evidence: <what was done or why not applicable>
knowledgeCandidates:
  - kind: guardrail/pitfall/verification
    title: <reusable project lesson>
    claim: <evidence-backed project claim>
    scope:
      components: [<component>]
      paths: [<path glob>]
      dependencies: [<dependency>]
      versions: [<version>]
      tags: [<tag>]
    appliesWhen: <trigger>
    directive: <action, not a shell command>
    rationale: <why this changes future work>
    evidenceRefs: [<current task evidence reference>]
risk: <remaining risk or none>

没有命中知识或没有新 candidate 时，对应列表写 []。Developer 不能把自己读到的 旧知识复述为新 candidate；每条 candidate 都需要当前任务产生的观测证据。

Orca 模式下用 orca-adapter.md §「Developer 回报 worker_done」的命令发送同样的字段。

---

5. Test 复测报告格式

Test 只回传证据和逐条结论，不下最终判定：

subject: <task_id> retest round <n>
attemptId: <task_id>-A<n>
env:
  worktree: <path>
  branch: <branch>
  commit: <short sha>
  baseUrl: <base_url>
commands:
  - <command_a>: passed/failed
signals:
  - <signal 1>: pass/fail (<evidence>)
  - <signal 2>: pass/fail (<evidence>)
browser: <snapshot / DOM / API evidence>
knowledgeChecks:
  - ref: <K-001@1>
    result: <passed|failed|not_applicable>
    evidence: <independent evidence>
regressionCandidates:
  - title: <reusable black-box case>
    surface: browser/api
    suite: smoke/full
    setup: <preconditions>
    steps: [<step>]
    expected:
      - kind: visible-text/api-status/api-field/url/interaction
        value: <observable signal>
    sourceKind: feature/bug
knowledgeCandidates:
  - kind: guardrail/pitfall/verification
    title: <new lesson found by Test>
    claim: <evidence-backed project claim>
    scope:
      components: [<component>]
      paths: [<path glob>]
      dependencies: [<dependency>]
      versions: [<version>]
      tags: [<tag>]
    appliesWhen: <trigger>
    directive: <action, not a shell command>
    rationale: <why this changes future work>
    evidenceRefs: [<independent evidence reference>]
conclusion: all-signals-pass / signals-failed
environmentFailure: null / <phase, evidence, impact, recovery suggestion>
notes: <observations, suspected cause, and independent candidate validation evidence>

没有适用项时列表写 []。Test 的知识结论仍只是证据；只有 Coordinator 能写入或 激活 knowledge.yaml。

Orca 模式下用 orca-adapter.md §「Test 回报复测结果」的命令发送同样的字段。

---

6. Coordinator 最终报告模板

本轮闭环完成。

已验证（Test 复测通过 + 终检）：
- <task_id>: <what passed>

环境事件：
- <task_id>: <原因、影响、是否恢复、Coordinator 下一步、userAction>

遗留：
- <task_id>: 三轮仍未通过，已记录为 leftover。最后失败证据：<evidence>

验证命令：
- <command>: passed

项目知识：
- 本轮采用：<knowledgeRefs and checks>
- 新增或更新：<active/stale/superseded entries written by Coordinator, or none>
- 待验证 candidate：<remaining candidates or none>

回归：
- 收获：新增/更新/退役/无回归 <case ids or none>
- 最近一次回归运行：<RR-id / passed|failed|n/a>

交付（未启用时写 n/a）：
- run/profile/status：<delivery run id / profile / validation_ready|review_ready|released|blocked|failed>
- PR/MR：<URL and head/base>
- 产物：<reference, digest, destination>
- 部署：<environment, health/rollback evidence>
- 待审批或未完成：<approval/blocked step or none>

工作树状态：
- <repo_path>: <git status summary>
- <dev_worktree>: <git status summary>

---

7. 派发给 Test 跑回归

请按回归目录对当前测试环境做独立黑盒回归。
suite: <smoke|full|custom>
baseUrl: <deployer 给出的地址>

用例（来自 select_regression.py，不要发明步骤）：
- <REG-id>: surface=<browser|api>
  setup: <setup>
  steps: <steps>
  expected: <expected signals>

要求：
- 先确认 Base URL 可访问；不可访问时回报 environmentFailure，不要编造产品失败。
- surface=browser 必须走真实页面交互，不能改成只打 API。
- 逐条对照 expected 回报 pass/fail 与证据。
- 不要修改源码，不要写 tasks.yaml / knowledge.yaml / regression.yaml。

完成后按 §5 的复测报告格式回报，signals 使用 REG-id。