Skip to content

An agentic skills framework & software development methodology that works.

Tone down review loops: single-pass plan review, raise issue bar

Jesse Vincent2c6a8a352d1a
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index 282bea6f6..8a1f48ef3 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -1,5 +1,15 @@
# Superpowers Release Notes
+## v5.0.4 (2026-03-16)
+
+### Review Loop Refinements
+
+- **Single whole-plan review** — plan reviewer now reviews the complete plan in one pass instead of chunk-by-chunk. Removed all chunk-related concepts (`## Chunk N:` headings, 1000-line chunk limits, per-chunk dispatch).
+- **Raised the bar for blocking issues** — both spec and plan reviewer prompts now include a "Calibration" section: only flag issues that would cause real problems during implementation. Minor wording, stylistic preferences, and formatting quibbles should not block approval.
+- **Reduced max review iterations** — from 5 to 3 for both spec and plan review loops. If the reviewer is calibrated correctly, 3 rounds is plenty.
+- **Streamlined reviewer checklists** — spec reviewer trimmed from 7 categories to 5; plan reviewer from 7 to 4. Removed formatting-focused checks (task syntax, chunk size) in favor of substance (buildability, spec alignment).
+- **Generic agent language** — brainstorm companion waiting page now says "the agent" instead of "Claude".
+
## v5.0.3 (2026-03-15)
### Bug Fixes
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md
index 724dc79e1..edbc2b579 100644
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -27,7 +27,7 @@ You MUST create a task for each of these items and complete them in order:
4. **Propose 2-3 approaches** — with trade-offs and your recommendation
5. **Present design** — in sections scaled to their complexity, get user approval after each section
6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
-7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 5 iterations, then surface to human)
+7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 3 iterations, then surface to human)
8. **User reviews written spec** — ask user to review the spec file before proceeding
9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
@@ -121,7 +121,7 @@ After writing the spec document:
1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
2. If Issues Found: fix, re-dispatch, repeat until Approved
-3. If loop exceeds 5 iterations, surface to human for guidance
+3. If loop exceeds 3 iterations, surface to human for guidance
**User Review Gate:**
After the spec review loop passes, ask the user to review the written spec before proceeding:
diff --git a/skills/brainstorming/spec-document-reviewer-prompt.md b/skills/brainstorming/spec-document-reviewer-prompt.md
index 212b36c53..35acbb611 100644
--- a/skills/brainstorming/spec-document-reviewer-prompt.md
+++ b/skills/brainstorming/spec-document-reviewer-prompt.md
@@ -19,32 +19,31 @@ Task tool (general-purpose):
| Category | What to Look For |
|----------|------------------|
| Completeness | TODOs, placeholders, "TBD", incomplete sections |
- | Coverage | Missing error handling, edge cases, integration points |
| Consistency | Internal contradictions, conflicting requirements |
- | Clarity | Ambiguous requirements |
- | YAGNI | Unrequested features, over-engineering |
+ | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
- | Architecture | Units with clear boundaries, well-defined interfaces, independently understandable and testable |
+ | YAGNI | Unrequested features, over-engineering |
+
+ ## Calibration
- ## CRITICAL
+ **Only flag issues that would cause real problems during implementation planning.**
+ A missing section, a contradiction, or a requirement so ambiguous it could be
+ interpreted two different ways — those are issues. Minor wording improvements,
+ stylistic preferences, and "sections less detailed than others" are not.
- Look especially hard for:
- - Any TODO markers or placeholder text
- - Sections saying "to be defined later" or "will spec when X is done"
- - Sections noticeably less detailed than others
- - Units that lack clear boundaries or interfaces — can you understand what each unit does without reading its internals?
+ Approve unless there are serious gaps that would lead to a flawed plan.
## Output Format
## Spec Review
- **Status:** ✅ Approved | ❌ Issues Found
+ **Status:** Approved | Issues Found
**Issues (if any):**
- - [Section X]: [specific issue] - [why it matters]
+ - [Section X]: [specific issue] - [why it matters for planning]
- **Recommendations (advisory):**
- - [suggestions that don't block approval]
+ **Recommendations (advisory, do not block approval):**
+ - [suggestions for improvement]
```
**Reviewer returns:** Status, Issues (if any), Recommendations
diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md
index ed67c5e32..26bae9af2 100644
--- a/skills/writing-plans/SKILL.md
+++ b/skills/writing-plans/SKILL.md
@@ -112,22 +112,17 @@ git commit -m "feat: add specific feature"
## Plan Review Loop
-After completing each chunk of the plan:
+After writing the complete plan:
-1. Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process.
- - Provide: chunk content, path to spec document
-2. If ❌ Issues Found:
- - Fix the issues in the chunk
- - Re-dispatch reviewer for that chunk
- - Repeat until ✅ Approved
-3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk)
-
-**Chunk boundaries:** Use `## Chunk N: <name>` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained.
+1. Dispatch a single plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process.
+ - Provide: path to the plan document, path to spec document
+2. If ❌ Issues Found: fix the issues, re-dispatch reviewer for the whole plan
+3. If ✅ Approved: proceed to execution handoff
**Review loop guidance:**
- Same agent that wrote the plan fixes it (preserves context)
-- If loop exceeds 5 iterations, surface to human for guidance
-- Reviewers are advisory - explain disagreements if you believe feedback is incorrect
+- If loop exceeds 3 iterations, surface to human for guidance
+- Reviewers are advisory — explain disagreements if you believe feedback is incorrect
## Execution Handoff
diff --git a/skills/writing-plans/plan-document-reviewer-prompt.md b/skills/writing-plans/plan-document-reviewer-prompt.md
index ce36cba13..2db280678 100644
--- a/skills/writing-plans/plan-document-reviewer-prompt.md
+++ b/skills/writing-plans/plan-document-reviewer-prompt.md
@@ -2,17 +2,17 @@
Use this template when dispatching a plan document reviewer subagent.
-**Purpose:** Verify the plan chunk is complete, matches the spec, and has proper task decomposition.
+**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition.
-**Dispatch after:** Each plan chunk is written
+**Dispatch after:** The complete plan is written.
```
Task tool (general-purpose):
- description: "Review plan chunk N"
+ description: "Review plan document"
prompt: |
- You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation.
+ You are a plan document reviewer. Verify this plan is complete and ready for implementation.
- **Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only
+ **Plan to review:** [PLAN_FILE_PATH]
**Spec for reference:** [SPEC_FILE_PATH]
## What to Check
@@ -20,33 +20,30 @@ Task tool (general-purpose):
| Category | What to Look For |
|----------|------------------|
| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
- | Spec Alignment | Chunk covers relevant spec requirements, no scope creep |
- | Task Decomposition | Tasks atomic, clear boundaries, steps actionable |
- | File Structure | Files have clear single responsibilities, split by responsibility not layer |
- | File Size | Would any new or modified file likely grow large enough to be hard to reason about as a whole? |
- | Task Syntax | Checkbox syntax (`- [ ]`) on steps for tracking |
- | Chunk Size | Each chunk under 1000 lines |
-
- ## CRITICAL
-
- Look especially hard for:
- - Any TODO markers or placeholder text
- - Steps that say "similar to X" without actual content
- - Incomplete task definitions
- - Missing verification steps or expected outputs
- - Files planned to hold multiple responsibilities or likely to grow unwieldy
+ | Spec Alignment | Plan covers spec requirements, no major scope creep |
+ | Task Decomposition | Tasks have clear boundaries, steps are actionable |
+ | Buildability | Could an engineer follow this plan without getting stuck? |
+
+ ## Calibration
+
+ **Only flag issues that would cause real problems during implementation.**
+ An implementer building the wrong thing or getting stuck is an issue.
+ Minor wording, stylistic preferences, and "nice to have" suggestions are not.
+
+ Approve unless there are serious gaps — missing requirements from the spec,
+ contradictory steps, placeholder content, or tasks so vague they can't be acted on.
## Output Format
- ## Plan Review - Chunk N
+ ## Plan Review
**Status:** Approved | Issues Found
**Issues (if any):**
- - [Task X, Step Y]: [specific issue] - [why it matters]
+ - [Task X, Step Y]: [specific issue] - [why it matters for implementation]
- **Recommendations (advisory):**
- - [suggestions that don't block approval]
+ **Recommendations (advisory, do not block approval):**
+ - [suggestions for improvement]
```
**Reviewer returns:** Status, Issues (if any), Recommendations