Code Quality Reviewer Prompt Template

Use this template when dispatching a code quality reviewer subagent.

Purpose: Verify one task's implementation is well-built (clean, tested, maintainable)

Only dispatch after spec compliance review passes.

Subagent (general-purpose):
  description: "Review code quality for Task N"
  prompt: |
    You are reviewing one task's implementation for code quality. This is a
    task-scoped gate, not a merge review — a broad whole-branch review happens
    separately after all tasks are complete.

    ## What Was Implemented

    [DESCRIPTION]

    ## Task Requirements (context only)

    [TASK_TEXT]

    ## Git Range to Review

    **Base:** [BASE_SHA]
    **Head:** [HEAD_SHA]

    ```bash
    git diff --stat [BASE_SHA]..[HEAD_SHA]
    git diff [BASE_SHA]..[HEAD_SHA]
    ```

    ## Read-Only Review

    Your review is read-only on this checkout. Do not mutate the working tree,
    the index, HEAD, or branch state in any way. Use tools like `git show`,
    `git diff`, and `git log` to inspect history.

    ## Scope

    Spec compliance was already verified by a separate reviewer. Do not
    re-check whether the code matches the requirements or the plan.

    Start from the diff. Read the changed files first. Inspect code outside
    the diff only to evaluate a concrete risk you can name — and name it in
    your report. Cross-cutting changes are legitimate named risks: if the
    diff changes lock ordering, a function or API contract, or shared mutable
    state, checking the call sites is the right method. Do not crawl the
    codebase by default.

    ## Tests

    The implementer already ran the tests and reported results with TDD
    evidence for exactly this code. Do not re-run the suite to confirm their
    report. Run a test only when reading the code raises a specific doubt
    that no existing run answers — and then a focused test, never a
    package-wide suite, race detector run, or repeated/high-count loop. If
    heavy validation seems warranted, recommend it in your report instead of
    running it. If you cannot run commands in this environment, name the
    test you would run.

    ## What to Check

    **Code quality:**
    - Clean separation of concerns?
    - Proper error handling?
    - DRY without premature abstraction?
    - Edge cases handled?

    **Tests:**
    - Do the new and changed tests verify real behavior, not mocks?
    - Are the task's edge cases covered?

    **Structure:**
    - Does each file have one clear responsibility with a well-defined interface?
    - Are units decomposed so they can be understood and tested independently?
    - Is the implementation following the file structure from the plan?
    - Did this change create new files that are already large, or
      significantly grow existing files? (Don't flag pre-existing file
      sizes — focus on what this change contributed.)

    ## Calibration

    Categorize issues by actual severity. Not everything is Critical.
    Acknowledge what was done well before listing issues — accurate praise
    helps the implementer trust the rest of the feedback.

    ## Output Format

    ### Strengths
    [What's well done? Be specific.]

    ### Issues

    #### Critical (Must Fix)
    [Bugs, data loss risks, broken functionality]

    #### Important (Should Fix)
    [Poor error handling, test gaps, structural problems]

    #### Minor (Nice to Have)
    [Code style, optimization opportunities]

    For each issue:
    - File:line reference
    - What's wrong
    - Why it matters
    - How to fix (if not obvious)

    ### Assessment

    **Task quality:** [Approved | Needs fixes]

    **Reasoning:** [1-2 sentence technical assessment]

Placeholders:

• [DESCRIPTION] — task summary, from implementer's report
• [TASK_TEXT] — the task's requirements text or plan reference, for context
• [BASE_SHA] — commit before this task
• [HEAD_SHA] — current commit

Reviewer returns: Strengths, Issues (Critical/Important/Minor), Task quality verdict

相对旧模板，这里保留了代码质量、测试质量、结构与可维护性维度，丢掉了 plan alignment、安全/扩展/生产就绪维度与合并判定；判定词从 "Ready to merge?" 换成 "Task quality: Approved | Needs fixes"。Scope 与 Tests 两节是"范围预算"与"测试预算"的正文——注意那句 "If you cannot run commands in this environment, name the test you would run"：这是为没有命令执行权限的只读评审 harness 预留的通道（设计文档提到 Antigravity 将评审模板映射到 `research` 类型，无命令权限）。

**验证（grep 即验收）：**

```bash
grep -c "requesting-code-review" skills/subagent-driven-development/code-quality-reviewer-prompt.md || echo ABSENT
# 期望：ABSENT（不再委托）

grep -n "Task quality:" skills/subagent-driven-development/code-quality-reviewer-prompt.md | head -2
# 期望：恰好一处（Output Format 的判定行；"Reviewer returns" 页脚写作 "Task quality verdict"，无冒号）

grep -n "worktree add\|Ready to merge" skills/subagent-driven-development/code-quality-reviewer-prompt.md || echo CLEAN
# 期望：CLEAN
```

通过后提交：

```bash
git add skills/subagent-driven-development/code-quality-reviewer-prompt.md
git commit -m "Make per-task quality reviewer prompt self-contained and task-scoped"
```

## Task 2：规格评审提示词的四处精确编辑

对象是 `skills/subagent-driven-development/spec-reviewer-prompt.md`（计划中的行号以 commit f55642e 时的文件为准）。四处编辑各自对应一个根因：

**编辑 1：加入 "judge from the diff" 条款。** 在 "Only read files in this diff. Do not crawl the broader codebase." 之后插入：

```
    Spec compliance is judged by reading the diff against the requirements.
    The implementer already ran the tests and reported TDD evidence — do not
    re-run them. If a requirement cannot be verified from this diff alone
    (it lives in unchanged code or spans tasks), report it as a ⚠️ item
    instead of broadening your search.
```

**编辑 2：裁剪只读章节。** 把含 `git worktree add /tmp/review-[SHA]` 操作说明的长句替换为：

```
    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history.
```

理由（设计文档）：diff 范围内的评审永远不需要检出另一个修订。

**编辑 3：让怀疑"有依据"。** 把

```
    The implementer finished suspiciously quickly. Their report may be incomplete,
    inaccurate, or optimistic. You MUST verify everything independently.
```

替换为

```
    Treat the implementer's report as unverified claims about the code. It may
    be incomplete, inaccurate, or optimistic. Verify the claims against the diff.
```

同等的不信任，但不再虚构一个事实（"完成得快得可疑"是未经证实的断言）。

**编辑 4：增加第三判定通道 ⚠️。** 把

```
    Report:
    - ✅ Spec compliant (if everything matches after code inspection)
    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
```

替换为

```
    Report:
    - ✅ Spec compliant (if everything matches after code inspection)
    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
    - ⚠️ Cannot verify from diff: [requirements you could not verify from the
      diff alone, and what the controller should check — report alongside the
      ✅/❌ verdict for everything you could verify]
```

⚠️ 通道解决了一个流程矛盾：流程图里的二元"通过/失败"菱形无法路由"无法从 diff 验证"的项，所以既不扩大搜索、也不静默放行，而是显式上报给控制器（控制器处理规则见 Task 4）。

**验证与提交：**

```bash
grep -n "suspiciously\|worktree add" skills/subagent-driven-development/spec-reviewer-prompt.md || echo CLEAN
# 期望：CLEAN

grep -c "⚠️" skills/subagent-driven-development/spec-reviewer-prompt.md
# 期望：2（judge-from-diff 条款 + 判定通道各一处）

git add skills/subagent-driven-development/spec-reviewer-prompt.md
git commit -m "Spec reviewer: judge from the diff, grounded skepticism, ⚠️ verdict channel"
```

## Task 3：实现者提示词——修复评审发现后必须重跑测试

"评审者不要重跑实现者的测试"这条规则有一个隐含前提：实现者每次修复后都会重跑测试。Task 3 把前提变成现实。在 `skills/subagent-driven-development/implementer-prompt.md` 的 "## Report Format" 一行之前插入新章节：

```
    ## After Review Findings

    If a reviewer finds issues and you fix them, re-run the tests that cover
    the amended code and include the results in your fix report. Reviewers
    will not re-run tests for you — your report is the test evidence.
```

**验证与提交：**

```bash
grep -n "After Review Findings" skills/subagent-driven-development/implementer-prompt.md
# 期望：一处匹配，位于 "## Report Format" 之前

git add skills/subagent-driven-development/implementer-prompt.md
git commit -m "Implementer prompt: re-run covering tests after fixing review findings"
```

## Task 4：SKILL.md 的六处控制器修改

这是改动量最大的一步：六处编辑让控制器（controller）获得"怎么写评审提示词、怎么处置 ⚠️ 项、终评走哪个模板"的显式规则。行号同样以 commit f55642e 为准。

**编辑 1：终评流程图节点指向宽模板。** 节点标签 "Dispatch final code reviewer subagent for entire implementation" 出现 3 次（当时在第 65、84、85 行），3 处全部替换为：

```
Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)
```

计划文档特别提醒：**Graphviz 节点按标签文本匹配——三处必须逐字节一致，否则图会多出一个幽灵节点**。

**编辑 2：评审模型选择从"最强大"改为"判断"。** 把

```
**Architecture, design, and review tasks**: use the most capable available model.

**Task complexity signals:**
```

替换为

```
**Architecture and design tasks**: use the most capable available model.

**Review tasks**: choose the model with the same judgment, scaled to the
diff's size, complexity, and risk. A small mechanical diff does not need the
most capable model; a subtle concurrency change does.

**Task complexity signals (implementation tasks):**
```

即：窄 diff 评审不再自动映射到"最宽代码库理解 → 最强模型"。

**编辑 3：在 "## Prompt Templates" 之前插入两个控制器指导章节：**

```
## Handling Spec Reviewer ⚠️ Items

The spec reviewer may report "⚠️ Cannot verify from diff" items — requirements
that live in unchanged code or span tasks. These do not block dispatching the
code quality reviewer, but you must resolve each one yourself before marking
the task complete: you hold the plan and cross-task context the reviewer
lacks. If you confirm an item is a real gap, treat it as a failed spec
review — send it back to the implementer and re-review.

## Constructing Reviewer Prompts

Per-task reviews are task-scoped gates. The broad review happens once, at the
final whole-branch review. When you fill a reviewer template:

- Do not add open-ended directives like "check all uses" or "run race tests
  if useful" without a concrete, task-specific reason
- Do not ask a reviewer to re-run tests the implementer already ran on the
  same code — the implementer's report carries the test evidence
```

⚠️ 项不阻塞派发动质量评审，但控制器必须在标记任务完成前逐条自行解决——因为它掌握评审者缺乏的计划与跨任务上下文；确认为真实缺口的按"规格评审失败"退回实现者。

**编辑 4：模板列表加终评指针。** 把

```
- code-quality-reviewer-prompt.md - Dispatch code quality reviewer subagent
```

替换为

```
- code-quality-reviewer-prompt.md - Dispatch code quality reviewer subagent
- Final whole-branch review: use superpowers:requesting-code-review's [code-reviewer.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/requesting-code-review/code-reviewer.md?utm_source=gitcode_repo_files)
```

这一步防止孤儿化：移除每任务质量提示词对 `code-reviewer.md` 的委托后，若不显式指路，最终评审模板就再没有引用入口。

**编辑 5：示例工作流改用新判定词。** 两处替换：

```
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
```

改为

```
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
```

```
Code reviewer: ✅ Approved
```

改为

```
Code reviewer: ✅ Task quality: Approved
```

终评者的 "ready to merge" 一行（当时在第 199 行）保持不变。

**编辑 6：Integration 章节措辞收窄。** 把

```
- **superpowers:requesting-code-review** - Code review template for reviewer subagents
```

改为

```
- **superpowers:requesting-code-review** - Code review template for the final whole-branch review
```

**验证（四条 grep）与提交：**

```bash
grep -c "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" skills/subagent-driven-development/SKILL.md
# 期望：3

grep -n "most capable available model" skills/subagent-driven-development/SKILL.md
# 期望：恰好一处（architecture/design 条目）

grep -n "Handling Spec Reviewer\|Constructing Reviewer Prompts" skills/subagent-driven-development/SKILL.md
# 期望：两个章节标题，均位于 "## Prompt Templates" 之前

grep -c "Task quality: Approved" skills/subagent-driven-development/SKILL.md
# 期望：2

git add skills/subagent-driven-development/SKILL.md
git commit -m "SDD controller: reviewer prompt budgets, ⚠️ handling, final-review pointer, model judgment"
```

## Task 5：新评测场景——植入一个只有任务级质量评审能抓住的缺陷

该场景放在 `evals/` **子模块**中（独立仓库 `superpowers-evals`）：在子模块里开分支开发，父仓库的 submodule 指针在收尾时统一提升。场景设计非常精巧：

- 脚手架生成一个很小的 Node 项目 + 两任务的计划：`formatUserReport` 与 `formatAdminReport`。
- 计划的 Task 2 实现代码**逐字复制** Task 1 的 banner 格式化逻辑（`"=".repeat(40)` 等）。
- 这种重复是**规格合规的**（需求只描述行为），所以规格评审应当放行它——被测的门正是每任务代码质量评审（抓 DRY 违规）。

**新增/修改的文件：**

- 新建 `evals/setup_helpers/sdd_quality_defect_plan.py`
- 修改 `evals/setup_helpers/__init__.py`（注册新脚手架）
- 新建 `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/` 下的 `story.md`、`setup.sh`、`checks.sh`

**Step 0，子模块开分支：**

```bash
cd evals
git checkout -b sdd-quality-defect-scenario
```

**Step 1，Python 脚手架助手。** 核心是一个两任务计划文本 `PLAN_BODY`（Task 1 定义 `formatUserReport`，Task 2 定义"Same banner layout"的 `formatAdminReport`，实现片段逐字重复）与 `scaffold_sdd_quality_defect_plan(workdir)` 函数：在 workdir 里 `git init -b main`、写入 `package.json`（含 `"test": "node --test"`）、把 `PLAN_BODY` 写到 `docs/superpowers/plans/report-plan.md`，然后 `git add -A` 提交 "initial: report formatter plan"。计划中两个任务的实现片段（即被植入的重复逻辑）形如：

```javascript
export function formatUserReport(user) {
  const banner = "=".repeat(40);
  const lines = [];
  lines.push(banner);
  lines.push(`Report for ${user.name} <${user.email}>`);
  lines.push(banner);
  lines.push(`Visits: ${user.visits}`);
  lines.push(banner);
  return lines.join("\n");
}
```

计划文档特别提醒：Python 源码中必须写成 `\\n`，这样生成的 Markdown 里是字面 `\n`，JS 读起来才是 `lines.join("\n")`。

**Step 2，注册助手。** 在 `evals/setup_helpers/__init__.py` 的 `scaffold_sdd_yagni_plan` 导入行之后加 `from setup_helpers.sdd_quality_defect_plan import scaffold_sdd_quality_defect_plan`，并在注册表中 `"scaffold_sdd_yagni_plan": scaffold_sdd_yagni_plan,` 之后加 `"scaffold_sdd_quality_defect_plan": scaffold_sdd_quality_defect_plan,`。

**Step 3，`story.md`（节选 frontmatter 与验收标准）：**

```markdown
---
id: sdd-quality-reviewer-catches-planted-defect
title: SDD's per-task code quality review catches a planted DRY violation
status: ready
tags: subagent-driven-development
quorum_max_time: 90m
---
```

正文告诉评测操作员：计划里 Task 2 的实现片段逐字复制 Task 1 的格式化逻辑，重复是规格合规的，规格评审应当放行，**被测的门是每任务代码质量评审**；让 agent 用 `superpowers:subagent-driven-development` 技能端到端执行计划，若它问成品放哪，回答"合并回 main 检出"；若质量评审标记了重复逻辑、实现者重构了它，让"评审-修复"循环完整演出来——这个循环正是被测行为。

```markdown
## Acceptance Criteria

- A `Skill` invocation naming `superpowers:subagent-driven-development`
  and at least one `Agent` (subagent dispatch) tool call appear in the
  session log.
- The duplicated report-formatting logic did not survive to the end of
  the run. Either (a) the implementer never introduced the duplication
  (wrote or self-reviewed its way to shared logic), or (b) the per-task
  code quality reviewer flagged the duplication as an issue and a
  review-fix loop removed it. A fail looks like the duplicated logic
  shipping with the per-task quality reviewer approving it, or the
  duplication being caught only by the final whole-branch review.
- The per-task quality reviewers stayed task-scoped: no package-wide
  test suites, race detector runs, or repeated/high-count test loops
  appear in reviewer subagent activity, and reviewers did not re-run
  the full test suite merely to confirm the implementer's report.
- `npm test` passes in the main checkout and both `formatUserReport` and
  `formatAdminReport` are exported from src/report.js.
```

注意第二条的"fail"定义：重复逻辑被**放行**（质量评审通过）、或**只被最终整分支评审抓到**，都算失败——它精确锁死了"任务级质量评审是抓住缺陷的机制"这一断言。第三条则直接对"任务级评审保持任务级范围"（无包级测试、无 race 检测、无重复跑套件）做了会话日志层面的断言。

**Step 4，`setup.sh`：**

```bash
#!/usr/bin/env bash
set -euo pipefail
uv run setup-helpers run scaffold_sdd_quality_defect_plan
```

记得 `chmod +x`。

**Step 5，`checks.sh`（无执行位）：**

```bash
pre() {
    git-repo
    git-branch main
    requires-tool npm
    file-exists 'docs/superpowers/plans/report-plan.md'
    file-contains 'docs/superpowers/plans/report-plan.md' 'formatAdminReport'
    file-contains 'docs/superpowers/plans/report-plan.md' 'repeat\(40\)'
}

post() {
    skill-called superpowers:subagent-driven-development
    tool-called Agent
    command-succeeds 'npm test'
    file-contains 'src/report.js' 'export function formatUserReport'
    file-contains 'src/report.js' 'export function formatAdminReport'
    command-succeeds 'test "$(grep -c "repeat(40)" src/report.js)" -le 1'
}
```

最后一条是**确定性的 DRY 门**：banner 构造 `"=".repeat(40)` 在最终文件里至多出现一次——共享而非逐函数复制。

**Step 6-7，子模块内验证并提交：**

```bash
cd evals
uv run quorum check     # 期望：通过，新场景列在列表中
uv run ruff check
uv run pytest -x -q

git add setup_helpers/sdd_quality_defect_plan.py setup_helpers/__init__.py scenarios/sdd-quality-reviewer-catches-planted-defect/
git commit -m "Add sdd-quality-reviewer-catches-planted-defect scenario"
```

## Task 6：静态验证扫查

不改文件，只做三条扫查：

```bash
# 1. 父仓库无悬空引用
grep -rn "requesting-code-review" skills/subagent-driven-development/
# 期望：匹配只出现在 SKILL.md（终评流程图节点 ×3、Prompt Templates 指针、Integration 条目），
# code-quality-reviewer-prompt.md 中没有任何匹配

grep -rn "Ready to merge" skills/subagent-driven-development/ || echo CLEAN
# 期望：CLEAN

# 2. 插件基础设施测试
bash tests/shell-lint/test-lint-shell.sh
# 期望：全部 PASS（新增 setup.sh 只在 evals 子模块里，有自己的检查）

# 3. 跨平台工具表仍自洽
grep -n "code-quality-reviewer" skills/using-superpowers/references/antigravity-tools.md skills/using-superpowers/references/gemini-tools.md
# 期望：两张表仍把 code-quality-reviewer 列为评审模板
# （新提示词里 "If you cannot run commands ... name the test you would run"
#  保持了只读 research 映射的有效性，无需改表）
```

## Task 7：Live before/after 评测（维护者门槛）

live quorum 运行会以宽松模式启动 agent CLI，是**受信维护者操作**（按计划，由维护者 Jesse 执行），且需要 `ANTHROPIC_API_KEY`。

**基线（改动前的技能）：**

```bash
cd evals
export SUPERPOWERS_ROOT=<主检出路径，未含本分支改动的 checkout>
uv run quorum run scenarios/sdd-rejects-extra-features --coding-agent claude
uv run quorum run scenarios/sdd-go-fractals --coding-agent claude
uv run quorum run scenarios/sdd-svelte-todo --coding-agent claude
uv run quorum run scenarios/spec-reviewer-catches-planted-flaws --coding-agent claude