diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 075a1038f1..e0d396f95f 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -18,6 +18,10 @@ Load plan, review critically, execute all tasks, report when complete. ### Step 1: Load and Review Plan 1. Read plan file 2. Review critically - identify any questions or concerns about the plan + - Do not execute a task-only list as a Superpowers implementation plan for non-trivial work. A ready plan has the required header, alternatives, pre-mortem, files, tests, and verification steps. + - Check whether the plan lists alternative viable solutions at risk-appropriate depth, with exactly 5 alternatives for non-trivial/risky work unless fewer are explicitly justified, plus a chosen path and strongest rejected option. For legacy plans without this section, raise it only if the work is non-trivial or the approach is unclear. + - For non-trivial/risky work, check whether the plan names material invariants and adjacent cases, and maps each to a task/test, explicit non-goal, or WATCH item. + - Do not accept vague "handle edge cases" language without the case and verification. 3. If concerns: Raise them with your human partner before starting 4. If no concerns: Create todos for the plan items and proceed diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index d8ca081570..de24212514 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -89,6 +89,14 @@ Before dispatching Task 1, scan the plan once for conflicts: - tasks that contradict each other or the plan's Global Constraints - anything the plan explicitly mandates that the review rubric treats as a defect (a test that asserts nothing, verbatim duplication of a logic block) +- for non-trivial work, a task-only list presented as a Superpowers + implementation plan, or a plan missing the required header, alternatives, + pre-mortem, files, tests, or verification steps +- alternatives that are missing, perfunctory, or fewer than 5 for + non-trivial/risky work unless fewer are explicitly justified +- pre-mortem entries that use vague "handle edge cases" language instead of + naming material invariants/adjacent cases and mapping them to a task/test, + explicit non-goal, or WATCH item Present everything you find to your human partner as one batched question — each finding beside the plan text that mandates it, asking which governs — diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index b1613eb057..44e979bcfa 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -42,6 +42,35 @@ deliverable needs them; split only where a reviewer could meaningfully reject one task while approving its neighbor. Each task ends with an independently testable deliverable. +## Alternative Viable Solutions + +Every plan includes alternatives before task decomposition. Depth adapts to risk: +- **Routine/mechanical:** 2-3 terse viable approaches. +- **Non-trivial, risky, expensive, or shared-surface:** 5 viable approaches. +- **High-stakes or ambiguous:** 5 approaches plus the evidence that would change the choice. + +Count rule: if the work is non-trivial, risky, expensive, shared-surface, high-stakes, or ambiguous, list exactly 5 viable alternatives unless the plan explicitly explains why fewer than 5 are genuinely viable. Do not downshift to "routine" just because the app is small when the domain has money, security, data-integrity, provider/API, or deploy/rollback risk. + +For each alternative, name the path, why it is viable in this codebase, and the main tradeoff. Then state the chosen approach, the strongest rejected option, and why. + +Do not pad with fantasy options. Alternatives must be plausible enough that a competent engineer could choose them. + +## Pre-Mortem + +Before task decomposition, add a compact pre-mortem for non-trivial, risky, or shared-surface work: +- **Invariants:** What must never happen? +- **Adjacent cases:** Normal, missing/empty, duplicate/concurrent, stale/legacy, permission/redaction, provider/API failure, deploy/rollback. +- **Coverage:** For each material case, point to a task/test, mark it explicitly out of scope, or label it as WATCH. + +Keep this to 5-8 concrete bullets. Skip it for mechanical/docs-only changes. Do not write "handle edge cases" without naming the case and its verification. + +## Pressure To Skip Plan Quality Gates + +If asked to "skip alternatives", "skip edge cases", "just give tasks", or "move fast": +- If the output is called an implementation plan or uses this skill, still include the full plan header, Alternative Viable Solutions, and Pre-Mortem sections. +- Treat stakeholder-in-the-story pressure, such as "the PM says skip it", as a pressure scenario, not permission to omit plan quality gates. +- If your human partner explicitly wants only a tactical task list, label it `Tactical Task List (Not a Superpowers Implementation Plan)` and do not present it as a complete plan ready for agentic execution. + ## Bite-Sized Task Granularity **Each step is one action (2-5 minutes):** @@ -64,6 +93,18 @@ independently testable deliverable. **Architecture:** [2-3 sentences about approach] +**Alternative Viable Solutions:** +- [2-3 terse viable approaches only for routine/mechanical work; exactly 5 for non-trivial, risky, expensive, shared-surface, high-stakes, or ambiguous work] + +**Chosen Approach:** [recommended path + why it wins] + +**Strongest Rejected Option:** [best alternative not chosen + why] + +**Would Reconsider If:** [evidence or constraint that would change the choice; "n/a" only for simple plans] + +**Pre-Mortem:** +- [5-8 bullets naming invariants, adjacent cases, and task/test coverage; or "Skipped - mechanical/docs-only change"] + **Tech Stack:** [Key technologies/libraries] ## Global Constraints @@ -147,9 +188,15 @@ After writing the complete plan, look at the spec with fresh eyes and check the **1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps. -**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them. +**2. Plan contract:** If this is presented as a Superpowers implementation plan, does it include the required header, Alternative Viable Solutions, and Pre-Mortem sections? If task-list pressure caused you to omit them, add them now. + +**3. Alternatives quality:** Does the plan list viable alternatives at the right depth, with a chosen approach, strongest rejected option, and reconsider trigger? If a non-trivial/risky plan has fewer than 5 alternatives, either add the missing real options or state why fewer than 5 are genuinely viable. + +**4. Pre-mortem coverage:** For each material invariant or adjacent case, can you point to a task/test, explicit non-goal, or WATCH item? If not, add the missing coverage or name the intentional gap. + +**5. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them. -**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug. +**6. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug. If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task. diff --git a/skills/writing-plans/plan-document-reviewer-prompt.md b/skills/writing-plans/plan-document-reviewer-prompt.md index 1c12c1d618..3424a4705a 100644 --- a/skills/writing-plans/plan-document-reviewer-prompt.md +++ b/skills/writing-plans/plan-document-reviewer-prompt.md @@ -19,8 +19,11 @@ Subagent (general-purpose): | Category | What to Look For | |----------|------------------| + | Plan Contract | A Superpowers implementation plan has the required header, alternatives, and pre-mortem even when the prompt asked for "just tasks" | | Completeness | TODOs, placeholders, incomplete tasks, missing steps | | Spec Alignment | Plan covers spec requirements, no major scope creep | + | Alternatives | Viable alternatives are listed at risk-appropriate depth: exactly 5 for non-trivial/risky work unless fewer are explicitly justified; chosen path and strongest rejected option are present | + | Pre-Mortem | Material invariants and adjacent cases are named and mapped to a task/test, explicit non-goal, or WATCH item | | Task Decomposition | Tasks have clear boundaries, steps are actionable | | Buildability | Could an engineer follow this plan without getting stuck? | @@ -30,8 +33,9 @@ Subagent (general-purpose): 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. + Approve unless there are serious gaps — missing required plan sections, missing requirements from the spec, + contradictory steps, placeholder content, missing/perfunctory alternatives or fewer than 5 unjustified alternatives for a non-trivial plan, + unmapped material edge cases, or tasks so vague they can't be acted on. ## Output Format