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.mdindex 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 Fixesdiff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.mdindex 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 recommendation5. **Present design** — in sections scaled to their complexity, get user approval after each section6. **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 proceeding9. **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.mdindex 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), Recommendationsdiff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.mdindex 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 Handoffdiff --git a/skills/writing-plans/plan-document-reviewer-prompt.md b/skills/writing-plans/plan-document-reviewer-prompt.mdindex 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