Slow Review Agents in Subagent-Driven Development v5.1.0

[qjbtj999]

Bug Report: Slow Review Agents in Subagent-Driven Development

Date: 2026-05-13
Plugin: superpowers@claude-plugins-official v5.1.0
Plugin cache path: ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/

---

Problem Recognition

When using the superpowers:subagent-driven-development skill to execute implementation plans, two review subagents are dispatched after each implementation task:

• Spec compliance reviewer ("spec reviewer")
• Code quality reviewer

Both reviewers exhibited extremely slow runtimes: 20–33 minutes each, even when providing only 2 paragraphs of feedback. The bottleneck was exhaustive, open-ended codebase exploration — reading dozens of files to build full context before performing what should be a focused review.

---

Root Cause Analysis

RC-1: Spec reviewer has no file scope (primary cause)

File: skills/subagent-driven-development/spec-reviewer-prompt.md

The spec reviewer prompt did not include a git range (BASE_SHA/HEAD_SHA). It was instructed:

"Read the actual code they wrote... Compare actual implementation to requirements line by line"

Without knowing which files changed, the general-purpose subagent had to search the entire codebase to find what the implementer modified. This caused an open-ended crawl of the repo.

By contrast, the code quality reviewer template already included:

BASE_SHA: [commit before task]
HEAD_SHA: [current commit]

...and instructed the reviewer to run git diff to scope its work. The spec reviewer had no equivalent.

RC-2: Model selection guidance over-prescribed powerful models for review (secondary cause)

File: skills/subagent-driven-development/SKILL.md

The model selection section read:

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

Grouping "review" with "architecture and design" caused the controller to dispatch reviewers as Opus. Spec compliance review is a mechanical diff-comparison task — it does not require maximum reasoning capability and runs significantly faster on cheaper models (Haiku/Sonnet).

---

Code Change List

Change 1 — Add git range to spec reviewer prompt

File: skills/subagent-driven-development/spec-reviewer-prompt.md

Before:

## What Implementer Claims They Built

[From implementer's report]

## CRITICAL: Do Not Trust the Report

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

**DO NOT:**
- Take their word for what they implemented
- Trust their claims about completeness
- Accept their interpretation of requirements

**DO:**
- Read the actual code they wrote
- Compare actual implementation to requirements line by line
- Check for missing pieces they claimed to implement
- Look for extra features they didn't mention

After:

## What Implementer Claims They Built

[From implementer's report]

## Git Range to Review

**Base:** [BASE_SHA — commit before this task]
**Head:** [HEAD_SHA — current commit]

Start by running:
```bash
git diff --stat [BASE_SHA]..[HEAD_SHA]
git diff [BASE_SHA]..[HEAD_SHA]

Only read files that appear in this diff. Do not explore the broader codebase.

CRITICAL: Do Not Trust the Report

The implementer's report may be incomplete, inaccurate, or optimistic.
You MUST verify everything independently against the actual diff.

DO NOT:

• Take their word for what they implemented
• Trust their claims about completeness
• Accept their interpretation of requirements
• Read files outside the git diff range

DO:

• Read the actual code they wrote (scoped to the diff)
• Compare actual implementation to requirements line by line
• Check for missing pieces they claimed to implement
• Look for extra features they didn't mention

**Why:** Gives the spec reviewer an explicit file scope. Eliminates open-ended codebase crawl. Mirrors the approach already used by the code quality reviewer.

---

### Change 2 — Fix model selection guidance for reviewers

**File:** `skills/subagent-driven-development/SKILL.md`

**Before:**

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

Task complexity signals:

• Touches 1-2 files with a complete spec → cheap model
• Touches multiple files with integration concerns → standard model
• Requires design judgment or broad codebase understanding → most capable model

**After:**

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

Spec compliance review: use a fast, cheap model. Spec review is mechanical —
diff-scoped comparison of code vs. requirements. Does not need a powerful model.

Code quality review: use a standard model. Quality judgment benefits from
reasoning but doesn't need maximum capability.

Task complexity signals:

• Touches 1-2 files with a complete spec → cheap model
• Touches multiple files with integration concerns → standard model
• Requires design judgment or broad codebase understanding → most capable model
• Spec compliance reviewer → cheap model (always diff-scoped)
• Code quality reviewer → standard model

**Why:** Decouples "review" from "architecture/design" in model selection. Spec review is mechanical (Haiku-appropriate); code quality review needs judgment (Sonnet-appropriate); architecture/design needs maximum reasoning (Opus-appropriate).

---

## How to Re-Apply After Plugin Update

When `superpowers@claude-plugins-official` is updated, the plugin cache directory changes. Re-apply the two changes above to the new version's files:

~/.claude/plugins/cache/claude-plugins-official/superpowers/<NEW_VERSION>/skills/subagent-driven-development/spec-reviewer-prompt.md
~/.claude/plugins/cache/claude-plugins-official/superpowers/<NEW_VERSION>/skills/subagent-driven-development/SKILL.md

Steps:
1. Find the new cache path: `ls ~/.claude/plugins/cache/claude-plugins-official/superpowers/`
2. Apply **Change 1** to `spec-reviewer-prompt.md`: insert the `## Git Range to Review` section between `## What Implementer Claims They Built` and `## CRITICAL: Do Not Trust the Report`, and add `- Read files outside the git diff range` to the DO NOT list.
3. Apply **Change 2** to `SKILL.md`: in the `## Model Selection` section, split the "Architecture, design, and review tasks" line into three separate entries (architecture/design → Opus, spec review → cheap, code quality → standard).

---

## Expected Outcome

| Metric | Before | After |
|--------|--------|-------|
| Spec reviewer runtime | 20–33 min | 1–3 min (diff-scoped) |
| Code quality reviewer runtime | 20–33 min | 5–10 min (already had git range) |
| Model for spec reviewer | Opus (inferred from "review tasks") | Haiku |
| Model for code quality reviewer | Opus (inferred from "review tasks") | Sonnet |

[obra]

Fixed in $SHA (on dev, will ship in the next release).

Thanks for the detailed report and root-cause analysis — the spec-reviewer-prompt asymmetry vs. code-quality-reviewer-prompt was exactly the issue. The fix mirrors what code-reviewer.md already does: gives the spec reviewer an explicit BASE_SHA/HEAD_SHA range and tells it to only read files in the diff, not crawl the broader codebase.

We did not take the secondary model-selection change from your report (Opus → Haiku for spec reviewer, etc.) — that's worth a separate discussion in its own issue if you'd like to pursue it. The diff-scoping alone should dramatically cut spec reviewer runtimes per your expected-outcome table.

— Claude Opus 4.7, Claude Code 2.1.150