Checkpoints - Adversarial Review

[larya-dot-eu]

Tip

TL;DR: The Superpowers skill is great, but adding a adversarial review phase — forcing Claude to "break the plan" before execution — consistently catches real bugs that the built-in self-review misses.

• I searched existing issues and this has not been proposed before

What problem does this solve?

The built-in writing-plans self-review is confirmatory — it checks coverage, types, and placeholders. It does not attempt to break the plan. After 90+ sessions using Superpowers (primarily Opus for specs/plans, Opus/Sonnet for execution), I consistently found that Claude in "completion state" produces plans that look correct but contain silent failures — wrong test commands, missing venv activations, fragile regexes, silently drifting field mappings. These only surface on first execution, costing tokens and rework.

Proposed solution

A dedicated adversarial review phase invoked between writing-plans and execution. The phase explicitly switches Claude's mode: instead of confirming the plan is complete, it is instructed to break it — trace intermediate states, run commands mentally, verify assumptions against the actual codebase, and surface findings categorized by fix type (surface fix → patch plan, architectural issue → rewrite spec, wrong problem → back to exploration). The exit gate is the user's approval, not Claude's own confidence.

What alternatives did you consider?

• Relying on the existing writing-plans self-review — insufficient, it's confirmatory not adversarial
• Adding more detail to specs — doesn't help when the plan itself contains unverified shell commands or env assumptions
• Manual review — valid, but happens too late; the adversarial pass catches the class of bug before execution, not during

The adversarial phase is not a competing workflow — it's a missing discipline layer that sits between planning and execution and complements all existing skills.

Is this appropriate for core Superpowers?

Yes. The problem — Claude over-confidence in completion state producing plans with unverified assumptions — is universal across project types, languages, and domains. It is not specific to my stack. Any team using writing-plans for complex multi-step work would benefit from a forced break-it pass before execution.

Environment (required)

Claude Code CLI on Ubuntu server, Opus 4.8 for spec/plan writing, Sonnet and sometimes Opus for execution, 90+ real sessions over several weeks using the full Superpowers workflow. The problem came up in live sessions — not inferred from documentation. Specific bugs were caught by this adversarial pass in multiple sessions that the built-in self-review passed without flagging.

Field	Value
Superpowers version	6.0.2
Harness (Claude Code, Cursor, etc.)	Claude Code
Harness version	v2.1.181
Your model + version	Opus 4.8 with high effort
All plugins installed	superpowers, Supabase, context7, vercel, gstack, code-review, frontend-design

Context

First of all, I absolutely love the Superpowers skill. It's an amazing skill and I rely on it every day. Thank you very much for sharing them with the community.

Please only read this if you have some spare time, as my findings may only apply to me, my terminal, my working methodology, and my past experiences (with my own work, teams, and different projects unrelated to coding).
However, if there's even a small chance that the Superpowers skill can be improved by 5%, then it might be worth our time.

If I work out the main idea, the superpowers planning with files approach solves the coding problems. It also makes some of the model and context loss assumptions disappear.
I try to keep my work simple and focus on just a couple of questions (the Ws/H framework).

I've searched through all the current issues posted and found some that relate to my "issue".
I think this is the discipline of some parts of the Superpowers skill as a whole framework.

For example, I have read these related reports:

• Controller skips spec/quality reviewer dispatch during subagent-driven-development #463 (discipline)
• writing-plans: plans over-specify implementation, leaving no room for executor judgment #895
• Iteration skill for post-execution plan refinement #921
  "Most real-world development lives in the middle: the implementation is 80-90% right, but needs targeted refinement."
• brainstorming: add research step before proposing approaches #983
• subagent-driven-development parallelizes tightly-coupled frontend tasks without coordination #995
• writing-plans: Enhanced review capabilities #1010
• subagent driven development could skip reviews for "easy" tasks.  #1120 (discipline)
• Proposal: maintaining-roadmap skill for cross-session priority orchestration #1192 ("pain")
• Group-based execution + review (reduce overhead across many small tasks) #1251
• Expose lifecycle events beyond SessionStart for external integration #1442
• writing-skills v5.0.7: '3+ combined pressures' anchor pattern substitutes count for standard (5 sites) #1487
• Add lifecycle extension system for user-defined workflow hooks #1566
  "But in practice, my colleagues and I keep running into moments where we want to inject a specific skill into the Superpowers workflow at a known transition point, like a compound learning phase after plan execution, a security review after code review, or a compliance check before merge, and there's no supported way to do it."
• RFC: require review admission receipts before extra SDD review passes #1614
• Proposal: Add a Human Acceptance Matrix for user-facing validation alongside TDD #1664
• Superpowers limitations in AI agent workflows (EDD support) #1671
• Proposal: a Decision Ledger + Design-Fidelity Gate so UI decisions survive the brainstorm → plan → impl → verify pipeline #1783
• Feature Request: Add a "Vision Quest" (Pre-Brainstorm) Skill #1766

In my opinion, none of these are complete solutions; rather, they are all complementary problems.

What attracted my attention was these comments:

So, this is very much how writing-plans was designed to operate. I've been running evals on a possible evolution of the planning process, but so far, the outcomes are all worse.
Originally posted by @obra in #895

I've definitely been thinking about this. I don't feel like I yet have a good handle on what the superpowers version of this is. But we want something here.
Originally posted by @obra in #921

I also liked the direction in which the discussion went in response to @marcindulak's comment (#895 (comment)) and his conclusion that "when the design documentation itself is inaccurate, agents that follow it may repeat mistakes", with which I agree to a certain extent.
The Superpowers skills in specifications and planning writing end with: Review and approve, which comes down to us.

I've read a lot of reports ending with "end-user feedback was that it was too token-intensive", and this is where I would like to strike a balance.
If you're only planning to make small changes to a few files, then you probably don't need a full review.
But if we could spend an extra 10–20k tokens with a simple command to review the specs and plans, how many of us would do it?
What if spending an extra 20k tokens on three out of ten sessions would save you 200–500k tokens on each session where issues are discovered at the end of implementation?

This is where I think #921 would be most valuable.

I've seen quite a few users requesting some "dedicated skills" that touch on different "disciplines (in my opinion)" of the current skill process.

But as @obra said here (#1614 (comment)) "Superpowers 5.0 shipped exactly this kind of multi-pass review-gate machinery — repeated spec/quality review cycles with admission-style controls. End-user feedback was that it was too token-intensive, and our own evals did not show a dramatic quality improvement to justify the cost. We deliberately simplified away from that approach."

Maybe you could just add an extra 'optional disciplinary step' to the code review request process?

I really hope I haven't fallen victim to the "AI Slop", but this is how I currently work. Here I'm linking to the basic workflow (https://github.com/obra/superpowers#the-basic-workflow), which I assume most of us are using with minor deviations. I have used this workflow for more than 90 sessions, mainly with Opus for specs and plan writing, and Opus/Sonet for executions, and sometimes Haiku as subagents.

So my workflow is as follows:

1. Before I start anything, I have a Project_Checklist.md file with all my questions and I let Claude ask me these questions and brainstorm each of them with me.
2. The brainstorming step then creates a spec that I use to create my Roadmap.md file for the project.
3. Then I use Brainstorming and my Planning.md file to write the specs for Phase 1, Step 1, Task 1 of my Roadmap.md.
4. So basically Superpowers steps: Brainstorming -> Specs Writing -> Plan Writing -> Self-review

I think that's the 'discipline' we really need from superpowers when making medium or big changes.

Here is a summary of the way I approach my projects with Superpowers.

Prerequisites    Load CLAUDE.md files, ROADMAP.md, relevant code — confirm with user
Phase 1          Context Priming       Confirm project understanding — user approves before Phase 2
Phase 2          Exploration           Ask only — define why + constraints + what's different
                 EXIT GATE             All 3 questions answered clearly before Phase 3
Phase 3          Spec.md Writing       Behavior, interfaces, edge cases, explicit assumptions
                 CHECKPOINT            Spec vs. codebase: conflicts + unverified assumptions fixed
                 OUTPUT                spec-[feature].html — sidebar nav, assumption warnings, checklist
Phase 4          Plan.md Writing       Ordered steps with exit states and verification
                 CHECKPOINT            5 adversarial questions answered with specific findings
                 OUTPUT                plan-[feature].html — step cards, dependency graph, checkpoint checklist
Phase 5          Adversarial Review    Break the plan — loop back by finding type
                 LOOP-BACK             Surface fix → Phase 4 | Arch issue → Phase 3 | Wrong problem → Phase 2
Phase 6          TDD Planning          Interfaces + test priority agreed before any code written
Phase 7          TDD Implementation    Red→Green→Refactor, vertical slices, scope creep rule enforced
Phase 8          Post-Implementation   Plan vs. reality, doc updates flagged
Phase 9          Living Doc Update     After each phase + proactively at ~X% context
Phase 10         Deployment & Release  Prove artifact locally → deploy → confirm health → then merge/seed/announce
Cross-phase      Execution Discipline  Honor skill checklists / open files before citing / verify before claiming ready

For example here is the Phase 4. Checkpoint after I wrote the specs and plan (questions answered):

1. Verification per step? Yes/No
2. Grouped by independent vs dependent testability? Yes/No
3. Everything extracted from codebase + conversation? Yes/No
4. Unverified external deps? Flag in-plan
5. Claims most expected to be wrong? Output

Than I switch claude to the next Phase 5 - Adversarial review:

Here's an example of exactly what Opus 4.8/high said:

... and that's exactly what caught yesterday's two real bugs before execution.
Given the stakes you named, I recommend running it on this plan before any code. The alternative is the writing-plans execution choice (subagent-driven vs inline).
How do you want to proceed?
 - Adversarial review first (recommended) — I switch to break-the-plan mode, trace intermediate states + dependency graph, fix findings, then execute.

After we ran the adversarial review:

Phase 5 complete.
Tracing intermediate states + the dependency graph + checking the plan against what the codebase actually does, I found no architectural or fundamental problems — the mirror is sound, response-shape parity holds, and gating is verified against real access.py.
  
But I broke it on four surface points, two of which would have failed on first command (exactly the yesterday-class bug):

Dependency graph — clean. 1→2→3→4→5→6 (core/backend) and 7→8→9 (frontend), 10 last.
No task consumes a later task's output; every task commits a green state. Well under the 1/3 rework threshold → surface fixes, patch in place (Phase 4 loop-back), no Phase 3 restart.

Findings (all verified against code just now):

  1. Wrong frontend test command — plan says npm run test -- --run, but package.json has "test": "vitest run", so that expands to vitest run --run (bad flag).
  Correct: npm run test or npm run test -- <path>. Would fail on first run.
  2. Backend venv not activated — plan's backend steps just cd backend && python -m pytest, but backend has its own backend/.venv (separate from core/.venv).
  Would fail on first run.
  3. score_specs_table regex is fragile/ugly — works on the test but brittle. Replacing with a clean line-based check.
  4. _PRODUCT_FIELD_INSTRUCTIONS ↔ PRODUCT_FIELD_ORDER can silently drift — a KeyError waiting to happen. Adding a guard test.

  Downgraded my earlier "biggest risk": the DS primitive props are actually verified — CategoryOutput.tsx already uses FieldCard/LayerHeader/SchemaBlock with the exact props and both
  layer="sga"/layer="schema" forms ProductOutput uses. The working component is the proof. Not a risk.

  Applying the four fixes now.

After the fixes, this was Claude's "Conclusion":

Structurally sound. Dependency order correct, no broken intermediate states (every task commits green, nothing consumes a later task).
Assumptions surfaced and verified against the live tree. Four surface fixes applied and recorded in the plan; two of them (--run flag, backend venv) would have failed on the very first command — caught here instead of mid-execution, which is the whole point of the pass.
  
  This is the answer to "what happened": the writing-plans built-in self-review (confirmatory: coverage/types/placeholders) ran and passed.
  This adversarial review (break-it: run the commands in your head, trace state, check assumptions against code) is what actually found the failing commands.
  Different check, real value — exactly the gap that cost tokens yesterday.
  The only planning.md exit-gate item left is your approval.

And here comes the commet from @GiveMe-A-Name "When fixing a bug, you often cannot fully plan the solution before you start investigating." (#895 (comment))

Again, I'm not a developer or a tech expert; I'm just talking from the point of view of a PM. My technical expertise covers basic HTML, CSS, PHP, shop systems, e-commerce and a number of different ERP + POS systems.

I try to get Claude to close his eyes and run the code through his head using my predefined rules to break down the plan and find issues.

Claude with Superpowers produces "amazing outputs" when he's in the "completion state", which makes me(us) think he's 100% correct.
In over 90 recent sessions using the Superpowers skill, I've found (and confirmed) that switching Claude's state gets me from an initial 1200–1400 lines in the written plans to almost 1600+ lines in each file every time.

To be honest, I'm starting to lose trust in Claude, and I think only the right people with the necessary knowledge can help improve things.

[obra]

We actually had this in 5.0 and got a lot of hate from end users about the additional performance hit and token spend.

I 100% agree that an adversarial review pass is a great thing to do there and would love to bring it back as an option.

[larya-dot-eu]

To address the token usage issue, i like to simplify the approach.

There is a common German saying: You must be able to afford to buy cheap (Du musst es dir leisten können, billig zu kaufen).

In the context of software dev and projects in general, it means that choosing a "cheap" or "quick" fix now often results in higher long-term costs due to maintenance and technical debt.

For personal projects or small teams, it comes down to a big trade-off:
Would they rather "pay" for a quick fix every few sessions, or invest in a more robust and "premium" solution from the start?

We can visualize this using the PM Triangle.
We have a limited budget (tokens) of 5 "blocks" to distribute across these three constraints. We need to decide where our priorities stand:

Constraint
Quality	Low	[ _	_	_ ]	Max
Speed	Slow	[ _	_	_ ]	Fast
Price	Expensive	[ _	_	_ ]	Cheap

Quality: How robust and error-free do we need the output to be?
Speed: How fast do we need the response or development cycle?
Price: How much are we willing to spend on token usage/infrastructure?

If we prioritize Speed and a cheap Price (moving those sliders to the right), Quality will inevitably suffer.
To reach a sustainable solution, we likely need to shift our focus toward Quality, which requires us to accept either a higher Price (in tokens) or lower Speed (in terms of complex, iterative processing).

How would you like us to allocate these 5 blocks?

(In most cases, my friends/team mates/clients initially place three blocks on quality and then just stare at the remaining two...)

Now, returning to the checkpoints/adversarial review proposal, I suggest we adopt a phased approach. First, we need to establish a baseline by answering some basic questions.
The questions to be answered are: who, what, why, when and where.

Once we have these answers, if you wish to proceed, we can then ask how, by which options, and through which mechanism.

If you want to dig a bit deeper afterwards and think it might help or be relevant, I can provide a complete example of the files I'm currently using as a "skin" for superpowers.

P.S. I tried to clarify as much as possible, but it's quite difficult to correctly translate the intention of the question and the expected output from German to English.
Who?
What?
Why?
When?
Where?
In what way?
How?
Through which options?
In what way?
With what?
(Wer? Was? Warum? Wann? Wo? Auf welche Weise? Wie? Durch welche? Auf welche Weise? Womit?)

[obra]

@larya-dot-eu What prompting do you have for this issue? What's your human partner's ideal outcome?

[larya-dot-eu]

For the adversarial review i prompt this in CC:

(as todays example):

First, read the planning.md file and confirm with OK. Yesterday, we wrote the plan for 2.2 Module 2 (products). You can find this plan at docs/superpowers/plans/2026-06-18-phase-2.2-module-2-product.md. Next, we will begin the adversarial review of the plan.

Than Claude executes the instructions from my planning.md file, the "skin" i was talking about.
But this is numbered phase in the planning workflow file that each implementation session runs after writing-plans and before execution. The core of it:

---

Phase 5 — Adversarial Review

Switch from generation mode to review mode. Your goal is to break the plan, not defend it.

Check:

• Trace each step's intermediate state: after this step, is the codebase consistent or is it broken between steps?
• Draw the actual dependency graph: what must already exist before each step can run?
• What did you observe in the codebase that is not yet documented in the plan?
• Absence is not confirmation. An empty grep, a green suite that never exercises the changed path, a missing file, a silent log — each means "unverified," not "safe." If a search returns nothing, widen it (wrong file, wrong name, wrong dir) and open the actual source before concluding the thing is absent or fine. Never infer a signature or behavior from a sibling's usage when you can read the definition.
• Re-attack the plan's own flagged risks first. Any claim the plan marked "most likely wrong" or "verify on contact" gets opened and confirmed against source in this review — it is the first thing to break, not the thing deferred to execution.

Loop-Back Decision

Finding	Action
Surface fix — wrong step order, missing verification point	Return to Phase 4 and fix the plan
Architectural issue — wrong interface, broken dependency, broken intermediate state	Return to Phase 3 and fix the spec
Fundamental problem — wrong approach or wrong problem being solved	Return to Phase 2 and re-explore

Rollback rule: If more than one-third of all steps of the plan need reworking, do not patch. Restart from Phase 3.

Exit gate: The plan is structurally sound. No broken intermediate states. Dependency order is correct. All assumptions are surfaced and verified. User has approved.`

---

Regarding the ideal outcome:

I know version 5.0 went there and took the token backlash.

My ideal outcome would be the optional version that you previously outlined: either an opt-in pass at the known plan-to-execution transition, or a 'triggered hook' for a checkpoint.

For example, if the plan only touches three files and creates one new file, the workflow ends with the normal plan review.

However, if the written plan touches X+ files, creates Y new files and is genuinely more advanced, it should simply prompt the user:

Hey, we ran the standard plan review, and it's quite complex. Would you like us to run the adversarial review for X, Y and Z?

This would be a simple yes/no question that would trigger the 'adversarial review' process.

But here's the tricky part: the user is asked to place three of the five blocks from the PM Triangle that I previously mentioned directly.

---

Heres a real example for reference:

The adversarial pass + TDD planning touched 5 files, wrote 3 new test files and in-place plan fixes, with zero production code written yet.

Surface area: 3 architectural and 2 language layers — core Python, FastAPI backend, TypeScript frontend — 19 files, 10 TDD tasks.

I ended with a plan of 1,571 lines + 3 new tests, that will touch 19 files across 3 code layers, 2 stacks, 10 tasks (one per task) and all the catches (wrong test command, wrong venv, fragile regex, field-mapping drift, a fixture that can't go green).

The alternative is meeting each of those on first execution, scattered across 19 files and 10 commits, where the signal is a confusing test failure instead of a one-line plan fix.

To sumarize:

• Creates 12 new files
• Edits 7 existing files
• 17 verification runs + 3 pre-flight baseline runs
• 7 design decisions (gstack)
• 8-field output contract

I was just finishing up the 6th Phase:

But the session tokens also absorbed my roadmap and planning files + the context from gstack.
So the genuine cost of the review is the verification reasoning.

So fixing 6 latent bugs before a single line of implementation comes with its cost.

and

[jhochenbaum]

@larya-dot-eu @obra my teams have also found a lot of benefit from adversarial reviews. I appreciate that that Superpowers can't make everyone happy in our infinite and infinitely changing setups, so would supporting an extension mechanism ala the issue and PR I filed a little while back help ease the burden? See:

Issue: #1566
PR: #1224

[larya-dot-eu]

@jhochenbaum well, I think we're both on the same page: you created a lifecycle extension system and I created a simple .md "skin".
But the main idea is almost the same. If this is included in future versions as optional stages, I think we will all benefit from it.

I don't know if anything has already changed, but the subagents definitely work differently now.

and