From 0a5f6c66020fdb1bd5a4a36aa6c6bcb2e022e974 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Mar 2026 05:54:28 +0000 Subject: [PATCH 1/2] feat(iterating-on-plans): add iteration skill for post-execution plan refinement Closes the structural gap in the SDD loop after plan execution. Instead of restarting from scratch or losing quality gates with ad-hoc chat, users can now iterate with full AI-powered scope classification and preserved review rigor. New skill: skills/iterating-on-plans/ - SKILL.md: 3-level router (Patch / Plan Update / Design Update) with hard gate requiring scope classification + user confirmation before any action - scope-classifier-prompt.md: subagent that reads the change request against the actual plan state (checkboxes), design doc, and prior discoveries to determine minimum rework level and blast radius - patch-implementer-prompt.md: focused implementer variant that injects prior discoveries, enforces strict scope discipline, and surfaces out-of-scope expansion as NEEDS_CONTEXT rather than silently expanding Modified skills: - subagent-driven-development/SKILL.md: offer iterate vs finish-branch after final code review completes (instead of auto-invoking finishing skill) - executing-plans/SKILL.md: same iteration offer after all tasks complete Addresses obra/superpowers#921 https://claude.ai/code/session_01Mwwc9jcY5KQF4ewEcUXeCJ --- skills/executing-plans/SKILL.md | 17 +- skills/iterating-on-plans/SKILL.md | 266 ++++++++++++++++++ .../patch-implementer-prompt.md | 106 +++++++ .../scope-classifier-prompt.md | 126 +++++++++ skills/subagent-driven-development/SKILL.md | 14 +- 5 files changed, 526 insertions(+), 3 deletions(-) create mode 100644 skills/iterating-on-plans/SKILL.md create mode 100644 skills/iterating-on-plans/patch-implementer-prompt.md create mode 100644 skills/iterating-on-plans/scope-classifier-prompt.md diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index e67f94c573..d9e2ab65f2 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -31,11 +31,25 @@ For each task: ### Step 3: Complete Development -After all tasks complete and verified: +After all tasks complete and verified, present: + +``` +Implementation complete. What next? + +1. **Finish the branch** — merge, PR, or discard (superpowers:finishing-a-development-branch) +2. **Iterate** — refine what was built (superpowers:iterating-on-plans) + +Which option? +``` + +**If option 1 chosen:** - Announce: "I'm using the finishing-a-development-branch skill to complete this work." - **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch - Follow that skill to verify tests, present options, execute choice +**If option 2 chosen:** +- **REQUIRED SUB-SKILL:** Use superpowers:iterating-on-plans + ## When to Stop and Ask for Help **STOP executing immediately when:** @@ -68,3 +82,4 @@ After all tasks complete and verified: - **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting - **superpowers:writing-plans** - Creates the plan this skill executes - **superpowers:finishing-a-development-branch** - Complete development after all tasks +- **superpowers:iterating-on-plans** - Offered after all tasks complete, if refinement is needed diff --git a/skills/iterating-on-plans/SKILL.md b/skills/iterating-on-plans/SKILL.md new file mode 100644 index 0000000000..d48940cec1 --- /dev/null +++ b/skills/iterating-on-plans/SKILL.md @@ -0,0 +1,266 @@ +--- +name: iterating-on-plans +description: Use after plan execution when you need to refine, fix, or extend what was built — without losing quality gates or restarting from scratch +--- + +# Iterating on Plans + +## Overview + +Bridge the gap between "execution complete" and "truly done." When implementation is 80–90% right but needs targeted refinement, this skill classifies the change request, routes it to the right rework level, and preserves all quality gates. + +**Announce at start:** "I'm using the iterating-on-plans skill to refine this implementation." + +**Three rework levels:** + +| Level | When to use | What happens | +|-------|-------------|--------------| +| **Patch** | Bug, typo, small behavioral tweak — isolated to 1–3 files, no design change | Mini-task → implementer subagent → 2-stage review | +| **Plan Update** | Missing requirement, scope gap, requirement change — no architectural shift | Edit plan in-place → re-run affected tasks via SDD | +| **Design Update** | Architectural change, new major capability, contradiction in design | Scoped re-brainstorm → new plan → SDD | + + +Do NOT make any code changes, edit the plan, or invoke any other skill before: +1. Running the scope classifier subagent +2. Presenting the classification + rationale to the user +3. Getting explicit user confirmation to proceed + +Misclassifying a change wastes more tokens than one confirmation message. + + +--- + +## Step 1: Load Context + +Before classifying anything, gather: + +**1a. Plan file** +- Locate the plan: `docs/superpowers/plans/` — find the most recent plan for this feature, or ask the user if ambiguous +- Note which tasks are `[x]` (complete) and which are `[ ]` (incomplete) + +**1b. Design doc** +- Locate the spec: `docs/superpowers/specs/` — find the corresponding design doc +- If missing, note it (classifier will work without it but with reduced accuracy) + +**1c. Prior discoveries** *(optional — proceed without if absent)* +- Check for an `## Accumulated Discoveries` section at the bottom of the plan file +- Check for `docs/superpowers/discoveries/-discoveries.md` +- If found, extract the full discoveries list — it will be injected into all subagents + +**1d. Change request** +- This is what the user described: the bug, missing feature, or architectural concern +- If the request is vague ("it doesn't feel right"), ask one clarifying question before classifying + +--- + +## Step 2: Classify the Change + +Dispatch a scope-classifier subagent using `./scope-classifier-prompt.md`. + +Provide the subagent with: +- The user's change request (verbatim) +- The full plan text (with checkbox states) +- The design doc (or note if absent) +- Prior discoveries (or note if absent) + +The classifier returns: +- `PATCH` | `PLAN_UPDATE` | `DESIGN_UPDATE` +- Rationale (why this level, not another) +- Blast radius (which files / tasks / design sections are affected) +- Change description (precise description of what needs to happen) +- For `PLAN_UPDATE`: list of completed task IDs that need to be un-checked and re-executed + +--- + +## Step 3: Present Classification and Get Confirmation + +**Always show the user the classification before acting.** Present it like this: + +``` +I've classified this as a [PATCH / PLAN UPDATE / DESIGN UPDATE]. + +**Why:** [Rationale from classifier — 1–2 sentences] + +**Blast radius:** [Files affected / Tasks affected / Design section affected] + +**What I'll do:** +[For PATCH]: Dispatch an implementer subagent to fix [X] in [files]. Two-stage review follows. +[For PLAN UPDATE]: Edit the plan in-place — mark tasks [N, M] incomplete, add [new tasks]. Re-execute via subagent-driven-development. +[For DESIGN UPDATE]: Start a scoped re-brainstorm focused on [section], preserving [what stays the same]. Normal flow follows: brainstorming → writing-plans → subagent-driven-development. + +Shall I proceed? +``` + +Wait for the user's confirmation. If they push back on the classification, re-classify with their input or adjust the approach manually. + +--- + +## Step 4: Execute the Routed Level + +### Route A — Patch + +1. Dispatch a patch implementer subagent using `./patch-implementer-prompt.md` + - Inject: mini-task description (from classifier), affected files, prior discoveries +2. After implementer reports DONE: + - **Spec compliance review** — dispatch spec-reviewer using `../subagent-driven-development/spec-reviewer-prompt.md` + - Scope the review: "Did this fix the stated issue and *only* that? No regressions, no scope creep." + - If ❌: implementer fixes → re-review until ✅ +3. **Code quality review** — dispatch code reviewer using `../subagent-driven-development/code-quality-reviewer-prompt.md` + - If issues found: implementer fixes → re-review until approved +4. Offer next step (see Step 5) + +### Route B — Plan Update + +1. **Edit the plan file in-place:** + - Un-check (`- [ ]`) any completed tasks the classifier flagged as affected + - Add new tasks at the end (or inline if they depend on specific completed tasks) + - Add a `## Iteration Note` section at the top of the plan with: + ```markdown + ## Iteration Note — [date] + **Change:** [one-sentence description] + **Tasks modified:** [list] + **Tasks added:** [list] + ``` +2. Commit the updated plan: + ```bash + git add docs/superpowers/plans/.md + git commit -m "plan: [brief description of iteration change]" + ``` +3. Announce: "Plan updated. Re-executing affected and new tasks." +4. **REQUIRED SUB-SKILL:** Use `superpowers:subagent-driven-development` — execute only the un-checked tasks (skip already-complete ones) +5. Inject prior discoveries into every implementer subagent dispatch (add them to the Context section of each implementer prompt) +6. Offer next step (see Step 5) + +### Route C — Design Update + +1. Summarize what to preserve for the user: + ``` + Before re-brainstorming, I'll preserve: + - [Completed tasks / components that don't change] + - [Constraints and tech stack decisions that stand] + + The re-brainstorm will be scoped to: [affected design section] + ``` +2. Confirm with user before invoking brainstorming +3. **REQUIRED SUB-SKILL:** Use `superpowers:brainstorming` + - Pass the existing design doc as starting context + - Scope the brainstorm explicitly: "We're revisiting [section] only. Everything else is locked." +4. Normal flow continues: `brainstorming → writing-plans → subagent-driven-development` + +--- + +## Step 5: Offer Next Step + +After completing any patch or plan update, present: + +``` +Iteration complete. What next? + +1. **Iterate again** — describe another change (superpowers:iterating-on-plans) +2. **Finish the branch** — merge, PR, or discard (superpowers:finishing-a-development-branch) +``` + +Do not automatically invoke `finishing-a-development-branch` — let the user decide if more iteration is needed. + +--- + +## Process Flow + +```dot +digraph iterating_on_plans { + rankdir=TB; + + "Load context\n(plan + spec + discoveries)" [shape=box]; + "Change request clear?" [shape=diamond]; + "Ask one clarifying question" [shape=box]; + "Dispatch scope classifier" [shape=box]; + "Present classification + rationale" [shape=box]; + "User confirms?" [shape=diamond]; + "Adjust classification" [shape=box]; + + "PATCH" [shape=box]; + "PLAN UPDATE" [shape=box]; + "DESIGN UPDATE" [shape=box]; + + "Dispatch patch implementer\n(with discoveries)" [shape=box]; + "Spec compliance review\n(scoped: fix only, no regression)" [shape=box]; + "Code quality review" [shape=box]; + + "Edit plan in-place\n(un-check affected, add tasks, add iteration note)" [shape=box]; + "Commit updated plan" [shape=box]; + "subagent-driven-development\n(un-checked tasks only, discoveries injected)" [shape=doublecircle]; + + "Summarize preserved work" [shape=box]; + "brainstorming\n(scoped, existing design as input)" [shape=doublecircle]; + + "Offer: iterate again OR finish branch" [shape=box]; + + "Load context\n(plan + spec + discoveries)" -> "Change request clear?"; + "Change request clear?" -> "Ask one clarifying question" [label="no"]; + "Ask one clarifying question" -> "Dispatch scope classifier"; + "Change request clear?" -> "Dispatch scope classifier" [label="yes"]; + "Dispatch scope classifier" -> "Present classification + rationale"; + "Present classification + rationale" -> "User confirms?" ; + "User confirms?" -> "Adjust classification" [label="no"]; + "Adjust classification" -> "Present classification + rationale"; + "User confirms?" -> "PATCH" [label="patch"]; + "User confirms?" -> "PLAN UPDATE" [label="plan update"]; + "User confirms?" -> "DESIGN UPDATE" [label="design update"]; + + "PATCH" -> "Dispatch patch implementer\n(with discoveries)"; + "Dispatch patch implementer\n(with discoveries)" -> "Spec compliance review\n(scoped: fix only, no regression)"; + "Spec compliance review\n(scoped: fix only, no regression)" -> "Code quality review" [label="✅"]; + "Spec compliance review\n(scoped: fix only, no regression)" -> "Dispatch patch implementer\n(with discoveries)" [label="❌ fix"]; + "Code quality review" -> "Offer: iterate again OR finish branch" [label="✅"]; + "Code quality review" -> "Dispatch patch implementer\n(with discoveries)" [label="❌ fix"]; + + "PLAN UPDATE" -> "Edit plan in-place\n(un-check affected, add tasks, add iteration note)"; + "Edit plan in-place\n(un-check affected, add tasks, add iteration note)" -> "Commit updated plan"; + "Commit updated plan" -> "subagent-driven-development\n(un-checked tasks only, discoveries injected)"; + "subagent-driven-development\n(un-checked tasks only, discoveries injected)" -> "Offer: iterate again OR finish branch"; + + "DESIGN UPDATE" -> "Summarize preserved work"; + "Summarize preserved work" -> "brainstorming\n(scoped, existing design as input)"; + "brainstorming\n(scoped, existing design as input)" -> "Offer: iterate again OR finish branch"; +} +``` + +--- + +## Key Principles + +- **Classify before acting** — never skip the classifier, never skip confirmation +- **In-place plan edits** — single source of truth; git preserves history +- **Discoveries always travel** — inject prior discoveries into every subagent, at every level +- **Full 2-stage review, scaled depth** — patch reviews are tighter in scope, not lighter in rigor +- **One iteration at a time** — complete the current iteration fully before accepting the next request +- **Never re-run completed tasks** — the plan's `[x]` state is the contract; only un-check what the classifier explicitly flags + +--- + +## Failure Modes to Avoid + +| Anti-pattern | Why it's wrong | +|---|---| +| Skipping classification and just fixing "obviously simple" bugs | Small fixes break cross-file contracts silently ("reference drift") | +| Re-running the entire plan because one task needs fixing | Wastes tokens, may re-introduce already-resolved issues | +| Starting a design update without summarizing what's preserved | Brainstorming skill may re-question settled decisions | +| Injecting all discoveries without filtering | Stale discoveries from prior architecture can mislead subagents | +| Accepting user's classification without running the classifier | User's framing is often incorrect; the classifier reads the actual code | + +--- + +## Integration + +**Offered by:** +- `superpowers:subagent-driven-development` — after all tasks complete +- `superpowers:executing-plans` — after all batches complete + +**Invokes:** +- `./scope-classifier-prompt.md` — classifies the change request +- `./patch-implementer-prompt.md` — implements patch-level fixes +- `../subagent-driven-development/spec-reviewer-prompt.md` — spec compliance review +- `../subagent-driven-development/code-quality-reviewer-prompt.md` — code quality review +- `superpowers:subagent-driven-development` — re-executes plan-level changes +- `superpowers:brainstorming` — handles design-level changes +- `superpowers:finishing-a-development-branch` — offered after iteration is complete diff --git a/skills/iterating-on-plans/patch-implementer-prompt.md b/skills/iterating-on-plans/patch-implementer-prompt.md new file mode 100644 index 0000000000..f62d630eb8 --- /dev/null +++ b/skills/iterating-on-plans/patch-implementer-prompt.md @@ -0,0 +1,106 @@ +# Patch Implementer Prompt Template + +Use this template when dispatching a patch implementer subagent (Route A — Patch level only). + +This is a focused variant of the standard implementer prompt. The task is already classified, +scoped, and described precisely. The implementer's job is to fix exactly what's specified +and nothing more. + +``` +Task tool (general-purpose): + description: "Patch: [one-line description of the fix]" + prompt: | + You are implementing a targeted patch. The scope of this work has already been + classified and confirmed. Your job is to fix exactly what is described below — + no more, no less. + + ## Prior Discoveries + + [If discoveries exist, paste the full list here. If none: omit this section entirely.] + + These are known gotchas from prior implementation work on this codebase. Read them + before touching any code. If your fix interacts with any of these, account for it. + + ## The Fix + + [VERBATIM change description from scope classifier output] + + ## Files in Scope + + [List of exact file paths from classifier's blast radius] + + ## Context + + [Scene-setting: what this component does, why the bug exists, what correct behavior looks like. + Include any relevant completed task context that helps the implementer understand the area.] + + ## Before You Begin + + If anything in the fix description is ambiguous — especially around: + - What "correct behavior" means exactly + - Whether other files outside the listed scope might be affected + - Whether prior discoveries conflict with the stated fix + + **Ask now.** One question at a time. Do not start work until you're clear. + + ## Your Job + + 1. Read the listed files to understand the current state + 2. Implement exactly the described fix — stay within the listed files unless unavoidable + 3. If you discover the fix requires touching files outside scope, **stop and report NEEDS_CONTEXT** + (do not expand scope on your own — the classifier may have missed blast radius) + 4. Write or update tests that verify the fix works and doesn't regress + 5. Run the test suite to confirm + 6. Commit your work: + ```bash + git add [files changed] + git commit -m "fix: [description of what was fixed]" + ``` + 7. Self-review (see below) + 8. Report back + + ## Scope Discipline + + This is a patch, not a refactor. You MUST NOT: + - Rename variables, functions, or files outside the immediate fix + - Restructure code that isn't broken + - Add features or "nice to have" improvements + - Change behavior in any path not directly related to the fix + + If you see problems nearby, note them in your report as concerns — don't fix them. + + ## Before Reporting Back: Self-Review + + Review your work with these patch-specific questions: + + **Correctness:** + - Does the fix address the stated issue precisely? + - Could this fix break anything in adjacent code paths? + - Did I check the prior discoveries list for anything relevant to this area? + + **Scope:** + - Did I touch only the files in scope (or documented why I had to go outside)? + - Did I add anything that wasn't part of the stated fix? + - Are my tests verifying the fix specifically, not just re-testing existing behavior? + + **Regression safety:** + - Did the full test suite pass after my fix? + - Are there tests that previously passed that now fail? + + If you find issues during self-review, fix them before reporting. + + ## Report Format + + When done, report: + - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT + - What exactly you changed (file:line references) + - Test results (what test, what it verifies, did it pass) + - Self-review findings (if any) + - Any scope expansion that occurred (files you had to touch outside the listed scope) + - Any new discoveries worth recording for future subagents working in this area + + Use DONE_WITH_CONCERNS if the fix works but you're uncertain about side effects. + Use NEEDS_CONTEXT if the fix requires touching files outside the listed scope. + Use BLOCKED if you cannot implement the fix as described. + Never silently expand scope — always report it. +``` diff --git a/skills/iterating-on-plans/scope-classifier-prompt.md b/skills/iterating-on-plans/scope-classifier-prompt.md new file mode 100644 index 0000000000..cebf9f9af6 --- /dev/null +++ b/skills/iterating-on-plans/scope-classifier-prompt.md @@ -0,0 +1,126 @@ +# Scope Classifier Prompt Template + +Use this template when dispatching the scope classifier subagent. + +**Purpose:** Determine the correct rework level for a change request — PATCH, PLAN_UPDATE, or DESIGN_UPDATE — by reasoning about blast radius, not just surface description. + +``` +Task tool (general-purpose): + description: "Classify iteration scope for: [one-line summary of change request]" + prompt: | + You are a scope classifier. Your job is to read a change request against an existing + implementation plan and design doc, then determine the minimum rework level required. + + ## Change Request + + [VERBATIM change request from user — paste exactly, do not paraphrase] + + ## Plan File (with completion state) + + [FULL TEXT of plan file — include all tasks, with [x] / [ ] checkbox states] + + ## Design Doc + + [FULL TEXT of design doc — or "Not available" if absent] + + ## Prior Discoveries + + [FULL TEXT of accumulated discoveries — or "None recorded" if absent] + + --- + + ## The Three Rework Levels + + **PATCH** — apply when ALL of the following are true: + - The change is a bug fix, typo, small behavioral tweak, or missing edge case + - It is isolated to 1–3 files with no interface changes visible to other components + - No task in the plan needs to be re-run or un-checked + - The design doc does not need to change + - It can be described as a single mini-task ("Fix X in file Y so that Z") + + **PLAN_UPDATE** — apply when ANY of the following are true: + - A requirement was missing or misunderstood and needs new plan tasks + - One or more completed tasks need to be redone because the approach was wrong + - A new sub-feature is needed that fits within the current design + - Interfaces between components need to change (but the architecture stays the same) + - The fix is too large or cross-cutting to be a single mini-task + + **DESIGN_UPDATE** — apply when ANY of the following are true: + - The architecture needs to change (different layers, different component boundaries) + - A new major capability is needed that the current design didn't anticipate + - There is a contradiction in the design that causes the implementation to be wrong + - The tech stack or data model needs to change + - Fixing this correctly would invalidate the majority of completed tasks + + --- + + ## Classification Rules + + 1. **Always classify at the minimum level that correctly addresses the change.** + If PATCH is sufficient, don't escalate to PLAN_UPDATE. If PLAN_UPDATE is sufficient, + don't escalate to DESIGN_UPDATE. + + 2. **Read the actual plan tasks, don't just read the change request.** + A user might say "small fix" when the fix actually requires re-running 3 tasks. + A user might say "big change" when it's actually a 2-line patch. Trust the plan, not the framing. + + 3. **Consider blast radius across completed tasks.** + If a completed task's output will be wrong after the fix, that task must be un-checked + and re-executed. List every such task explicitly. + + 4. **Watch for reference drift.** + A change to a shared interface (types, function signatures, exported APIs) affects every + task that consumed that interface — even if only one task introduced the bug. + + 5. **Be conservative with DESIGN_UPDATE.** + Most things that feel architectural are actually plan-level. Only escalate to DESIGN_UPDATE + if the design doc itself is wrong or the change cannot be expressed as a set of plan tasks. + + --- + + ## Prior Discoveries — How to Use Them + + If discoveries are present, use them to: + - Identify which tasks touched the same system areas and may have the same gotchas + - Flag if the change request runs against a known discovery ("Note: Discovery 3 says X, + this fix assumes the opposite — confirm with user before proceeding") + - Determine if the change request is caused by a known gotcha that wasn't fully fixed + + --- + + ## Your Output + + Respond with exactly this structure: + + ### Classification + PATCH | PLAN_UPDATE | DESIGN_UPDATE + + ### Rationale + [2–3 sentences: why this level, and specifically why not the level above or below it] + + ### Blast Radius + [For PATCH]: + - Files to change: [list with exact paths] + - Completed tasks affected: None + + [For PLAN_UPDATE]: + - Completed task IDs to un-check and re-execute: [list — e.g. "Task 3, Task 7"] + - New tasks to add: [brief description of each new task needed] + - Files likely affected: [list] + + [For DESIGN_UPDATE]: + - Design sections to revisit: [list] + - Completed work to preserve: [list of tasks/components that don't need to change] + - Files likely affected: [list] + + ### Change Description + [For PATCH]: A single mini-task description, precise enough to hand directly to an implementer: + "Fix [specific behavior] in [file] so that [observable outcome]." + + [For PLAN_UPDATE]: What the plan update achieves in one sentence, plus list of task modifications. + + [For DESIGN_UPDATE]: What the re-brainstorm scope is, and what must remain locked/preserved. + + ### Discovery Conflicts + [List any prior discoveries that conflict with or complicate this change — or "None" if clean] +``` diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 5150b18632..eaa97bec8e 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -62,6 +62,8 @@ digraph process { "More tasks remain?" [shape=diamond]; "Dispatch final code reviewer subagent for entire implementation" [shape=box]; "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; + "Offer: finish branch OR iterate" [shape=diamond]; + "Use superpowers:iterating-on-plans" [shape=box style=filled fillcolor=lightyellow]; "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)"; "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?"; @@ -80,7 +82,9 @@ digraph process { "Mark task complete in TodoWrite" -> "More tasks remain?"; "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"]; "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"]; - "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch"; + "Dispatch final code reviewer subagent for entire implementation" -> "Offer: finish branch OR iterate"; + "Offer: finish branch OR iterate" -> "Use superpowers:finishing-a-development-branch" [label="finish"]; + "Offer: finish branch OR iterate" -> "Use superpowers:iterating-on-plans" [label="iterate"]; } ``` @@ -196,7 +200,12 @@ Code reviewer: ✅ Approved [Dispatch final code-reviewer] Final reviewer: All requirements met, ready to merge -Done! +Implementation complete. What next? + +1. **Finish the branch** — merge, PR, or discard (superpowers:finishing-a-development-branch) +2. **Iterate** — refine what was built (superpowers:iterating-on-plans) + +[User chooses option 1 or 2] ``` ## Advantages @@ -269,6 +278,7 @@ Done! - **superpowers:writing-plans** - Creates the plan this skill executes - **superpowers:requesting-code-review** - Code review template for reviewer subagents - **superpowers:finishing-a-development-branch** - Complete development after all tasks +- **superpowers:iterating-on-plans** - Offered after all tasks complete, if refinement is needed **Subagents should use:** - **superpowers:test-driven-development** - Subagents follow TDD for each task From c3226269de6d6e8b3b7f41525eef64e69bb6a678 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Mar 2026 13:06:23 +0000 Subject: [PATCH 2/2] refactor(iterating-on-plans): close loopholes found in adversarial pressure testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RED-GREEN-REFACTOR testing identified two gaps: 1. Step 3 override handling was too vague ("adjust manually") — agents could silently accept user downgrades of classification level without explaining risk. Fixed: explicit guidance to make risk transparent, give specific affected task info, defer to informed user decision, document override. 2. Patch implementer was ambiguous on partial completion when out-of-scope files discovered mid-fix. Fixed: commit in-scope completed work first, then report NEEDS_CONTEXT for out-of-scope findings. Both fixes verified under pressure testing. Added both patterns to the Failure Modes table. https://claude.ai/code/session_01Mwwc9jcY5KQF4ewEcUXeCJ --- skills/iterating-on-plans/SKILL.md | 14 +++++++++++++- .../iterating-on-plans/patch-implementer-prompt.md | 7 +++++-- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/skills/iterating-on-plans/SKILL.md b/skills/iterating-on-plans/SKILL.md index d48940cec1..301c13dbd4 100644 --- a/skills/iterating-on-plans/SKILL.md +++ b/skills/iterating-on-plans/SKILL.md @@ -91,7 +91,17 @@ I've classified this as a [PATCH / PLAN UPDATE / DESIGN UPDATE]. Shall I proceed? ``` -Wait for the user's confirmation. If they push back on the classification, re-classify with their input or adjust the approach manually. +Wait for the user's confirmation. + +**If the user disagrees with the classification level** (e.g., insists a PLAN_UPDATE is "just a patch"): +- Do NOT silently accept the downgrade +- Make the risk explicit: explain specifically which completed tasks will be wrong after the change and why +- Give the user enough information to make an informed decision +- Defer to the user once they confirm they understand the risk — but document their override in the plan as an `## Iteration Note` +- Never pretend the risk doesn't exist to avoid friction + +Example response when user overrides: +> "I hear you — the edit itself is one line. The reason I flagged PLAN_UPDATE is that Task 5 calls `User.save()` and compares against the stored value directly. After this change that comparison will break silently. If you've already accounted for that, treat this as a patch and I'll proceed immediately. If not, Tasks 5 and 7 need re-running. Which do you prefer?" --- @@ -247,6 +257,8 @@ digraph iterating_on_plans { | Starting a design update without summarizing what's preserved | Brainstorming skill may re-question settled decisions | | Injecting all discoveries without filtering | Stale discoveries from prior architecture can mislead subagents | | Accepting user's classification without running the classifier | User's framing is often incorrect; the classifier reads the actual code | +| Silently accepting user's override of classifier level | Make the risk explicit first — "just do what they say" leaves silent breakage | +| Discarding in-scope completed work when out-of-scope files are found | Commit the valid in-scope work, then report NEEDS_CONTEXT for the rest | --- diff --git a/skills/iterating-on-plans/patch-implementer-prompt.md b/skills/iterating-on-plans/patch-implementer-prompt.md index f62d630eb8..82e11c869a 100644 --- a/skills/iterating-on-plans/patch-implementer-prompt.md +++ b/skills/iterating-on-plans/patch-implementer-prompt.md @@ -47,8 +47,11 @@ Task tool (general-purpose): 1. Read the listed files to understand the current state 2. Implement exactly the described fix — stay within the listed files unless unavoidable - 3. If you discover the fix requires touching files outside scope, **stop and report NEEDS_CONTEXT** - (do not expand scope on your own — the classifier may have missed blast radius) + 3. If you discover the fix requires touching files outside scope: + - **Commit any in-scope work you have already completed** (don't discard valid work) + - **Report NEEDS_CONTEXT** — describe exactly which out-of-scope files are affected and why + - Do not expand scope on your own — the classifier may have missed blast radius, or + those files may have other owners, callers, or tests that need separate consideration 4. Write or update tests that verify the fix works and doesn't regress 5. Run the test suite to confirm 6. Commit your work: