Iteration skill for post-execution plan refinement

[andreasteich-blueits]

Is your feature request related to a problem? Please describe.

After completing an SDD execution cycle (brainstorm → write-plan → execute-plan), there's no structured workflow for iterating on the result. When I discover that changes are needed — a missed edge case, an additional feature, or a design adjustment — I'm left without clear guidance on how to proceed within the Superpowers framework.

In practice, this leads to one of two suboptimal outcomes:

1. Falling back to vibe coding: I continue chatting in the same session, making ad-hoc changes without the structured review and subagent isolation that made the initial implementation reliable. This defeats the purpose of using Superpowers in the first place.

2. Starting from scratch with brainstorm: Running the full brainstorm → plan → execute cycle again, which is overkill when the core design is sound and only incremental changes are needed. This wastes significant tokens and time on re-establishing context that already exists.

The gap is between "everything went perfectly, merge and done" and "the whole approach was wrong, start over." Most real-world development lives in the middle: the implementation is 80-90% right, but needs targeted refinement.

Describe the solution you'd like

A dedicated iteration skill (e.g. superpowers:iterate or superpowers:refine-plan) that provides a structured workflow for post-execution changes. The skill would:

1. Assess the scope of changes needed — Ask the user what needs to change and categorize the delta (bugfix, missing requirement, new feature, architectural adjustment).

2. Route to the appropriate level of rework:

   • Patch-level (small fixes, single-file changes): Generate a focused mini-plan with 1-3 tasks appended to the existing plan, execute via SDD with review.
   • Plan-level (new tasks, modified requirements): Update the existing plan document — add/modify/remove tasks while preserving completed ones — then re-run execute-plan for the new/changed tasks only.
   • Design-level (architectural changes): Trigger a scoped re-brainstorm that takes the existing design doc as input and focuses only on what's changing, then flows into plan update and execution.

3. Preserve context from the previous cycle — Reference the existing design doc and plan, acknowledge what was already implemented successfully, and avoid re-implementing completed tasks.

4. Maintain the same quality gates — New/modified tasks still go through spec compliance review and code quality review via subagents, just like the initial execution.

Example workflow

User: "The auth flow works but we forgot rate limiting on the login endpoint,
       and the error messages need to be more specific."

Claude (with iterate skill):
→ Reads existing plan, identifies completed tasks
→ Categorizes: 1 new requirement (rate limiting) + 1 modification (error messages)
→ Routes to plan-level iteration
→ Generates 2-3 new tasks referencing existing implementation
→ Executes via SDD with review
→ Updates plan doc to reflect iteration

Describe alternatives you've considered

• Manually editing the plan doc and re-running execute-plan: This works but requires the user to know the plan format, understand which tasks to mark as done, and manually write new task descriptions to the same quality standard. It's the current "best practice" workaround but isn't guided by a skill.

• Using systematic-debugging for fixes: Works for bugs but doesn't cover new requirements or design changes. Debugging is about root-cause analysis, not plan iteration.

• Starting a new session with a fresh brainstorm: Loses all context from the previous cycle. Expensive in tokens and time.

Additional context

Related issues and prior art

• brainstorming/writing-plans SKILL efficiency #512 discusses plan efficiency and splitting plans into smaller files — iteration would benefit from (and could drive) this improvement
• Spec review for writing-plans #229 asks about a design spec feedback loop in writing-plans — an iteration skill would naturally address this gap
• The finishing-a-development-branch skill already offers "keep working" as an option, but doesn't provide structure for how to keep working

Why this matters for the Superpowers philosophy

Superpowers is built on the idea that structured process beats improvisation. But right now, the structure ends after the first execution pass. Real software development is inherently iterative — first drafts are rarely final. Extending the structured workflow into the iteration phase would close the loop and keep users from falling back into unstructured vibe coding exactly when discipline matters most.

[yumingqiao]

+1, in addition to what @andreasteich-blueits says above, I find once you entered this refinement process, the original plan is not followed. For example, I have the testing criteria in the original plan, but once I entered the refinement process, superpower doesn't respect the testing plans anymore.

[raye-deng]

The gap you describe between "merge and done" and "start over" is where most AI-generated regressions hide, in my experience.

The specific failure mode I see: the initial SDD cycle produces structurally sound code, but the iteration phase — where developers drop into ad-hoc chat mode — introduces the kinds of defects that traditional quality gates completely miss:

1. Reference drift — The iteration touches file A, but the original plan established contracts with files B and C. The ad-hoc change breaks those contracts silently because there is no plan-level awareness of cross-file dependencies.

2. Phantom dependencies — During iteration, the model suggests a new import that sounds plausible but references a package version or API that does not actually exist on the registry. TypeScript compiles (structural typing), tests pass (mocked paths), production crashes.

3. Scope regression — "Just fix this one thing" turns into the model helpfully refactoring adjacent code, reintroducing a pattern the original plan specifically avoided.

A refinement skill would help with the planning side. The complementary piece is a verification layer that runs after each iteration cycle — something that checks the actual code output against deterministic invariants (registry existence, API deprecation status, cross-file contract consistency) regardless of whether the change came from a full plan or a quick chat.

We have been building exactly this kind of post-execution verification: npx @opencodereview/cli scan . --sla L1 — it catches the class of defects that survive both the planning phase and the iteration phase because they are structurally invisible to the model.

[Maxson-dev]

+1, based.

[obra]

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.