Adversarial review findings (A1-A7, D3):
- BLOCKER A1: the re-gating tripwires lived only in the HARD-GATE, but
the skip decision happens at the description (our own GREEN-attempt-1
evidence). The description now carries the tripwires: adds a
file/dependency, touches schema/API/persisted data, deletes or
disables anything, alters behavior/security posture, >1 plausible
reading.
- A2: "a schema/API/data question" was defeated by "the user answered
the question"; now touch-based ("even if the user stated the desired
outcome").
- A3: destructive changes and behavior/security-visible changes had no
tripwire (pure removals were structurally invisible); both added.
"a literal config value change" example now qualified ("with no
security or behavioral consequences").
- A4: the checkbox example no longer teaches hedge-phrase = fully
specified ("where the context leaves nothing to choose").
- A5: "EVERY project regardless of perceived simplicity" now ends
"with exactly one exception below" instead of contradicting it.
- A6: rationalization table added (codebase-pattern, infer-the-obvious,
hedge-phrase, asking-wastes-time).
- A7: anti-pattern opener is a claim again ("Anything with open
decisions goes through this process").
- D3: exception states TDD and verification-before-completion still
apply, so the fast path does not read as zero-oversight.
Description: 689 chars (limit 1024), YAML-validated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The HARD-GATE ("EVERY project regardless of perceived simplicity") plus
the anti-pattern list naming "a config change" made design+approval
mandatory even for fully-specified trivial asks — all 6 agents in the
2026-06-09 quorum sweep ran a multi-option design flow for "a basic
checkbox, nothing fancy" (cost-checkbox-over-trigger failed 6/6).
Two layers, because routing happens before skill content is read
(GREEN attempt 1 proved it: the agent invoked the skill on the
description's mandate and only then saw the in-skill exception, and
the invocation itself is the cost event):
- description: carve-out visible at skill-selection time — zero open
design decisions, fully specified trivial change → implement
directly without invoking.
- HARD-GATE: matching exception with objective re-gating tripwires
(new file/dependency, schema/API/data question, >1 plausible
interpretation, user frames it as a feature/project), and the
anti-pattern section now distinguishes "seems simple" (a
rationalization when decisions exist) from "contains every decision"
(the exception). "A config change" moves from the all-of-them list
to the exception's example.
The repo's acceptance test ("Let's make a react todo list" must
auto-trigger brainstorming) is unaffected: a react todo list leaves
many decisions open and todo lists remain in the anti-pattern list.
TDD evidence (quorum):
- RED: cost-checkbox-over-trigger fails 6/6 agents (batch 2026-06-09);
GREEN attempt 1 with in-skill exception only: still fail (invoked
via description, then asked a clarifying question)
- GREEN: cost-checkbox-over-trigger-claude-20260610T004320Z-a30e pass —
no brainstorming invocation, agent cited the exception verbatim,
checkbox landed in 31s
- Canary: cost-spec-plan-duplication-claude-20260610T004506Z-22ea pass —
a real feature still triggers the full brainstorm→spec→plan flow
(and the stacked writing-plans reference discipline holds)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Staff-review findings (4-reviewer panel):
- Reference paragraph rewritten 170→123 words preserving every
behavioral condition (paraphrase/summarize coverage, no-skip guard,
WHAT-WHY/HOW split, No Placeholders boundary, drift counter,
zero-context rescope); fixes the "(brainstorming did)" syntax.
- **Spec:** header bracket: cut the never-skip sermon duplicated from
the Overview (same loaded document); the conditional none-branch
stays.
- executing-plans Step 1 now reads the spec the plan cites — plans are
no longer self-contained, and the non-subagent execution path was
never told (the eval only exercised the SDD consumer).
- writing-plans plan-location preference line gets the same
existing-dir-is-not-a-preference guard as the spec path.
- brainstorming: deduplicate the docs/specs/ prohibition (step 6
parenthetical stays; After-the-Design bullet was the second
statement in one file).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adversarial review findings (C1, C2, C3, C5, A8, F3):
- "never restate" did not cover paraphrase/summary — the actual failure
mode in the RED evidence; now "never restate, paraphrase, or summarize".
- The No Placeholders intra-plan repetition mandate gave a symmetric
argument for re-inlining the spec; the rule now draws the line:
repetition WITHIN the plan is required, copying FROM the spec is not.
- Drift argument was invertible ("snapshot to avoid drift"); now states
snapshots hide drift.
- **Spec:** header gets a no-spec branch (state requirements once in
the header, not per task) instead of inviting "no spec, rule is moot".
- Brainstorming path bullet: an existing differently-named docs dir is
not a "user preference" override.
- Execution Handoff now notes review fanout scales (forward-ref to
SDD's Proportionality rule) instead of promising unconditional
two-stage review.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
writing-plans told agents to "document everything they need to know"
assuming zero context — every agent in the 2026-06-09 six-agent quorum
sweep obeyed and restated the entire spec inline in the plan
(cost-spec-plan-duplication failed 5/5 completed agents; pi's plan was
683 lines of duplicated spec).
- writing-plans: state the division of labor — spec owns WHAT/WHY,
plan owns HOW; cite the spec by path/section, never restate it.
"Zero context" means mechanically executable steps, not duplication.
Add a **Spec:** line to the plan header template.
- brainstorming: close the path loophole the re-run exposed — claude
shortened docs/superpowers/specs/ to docs/specs/ in 2/2 runs; both
path mentions now explicitly forbid the shortening.
TDD evidence (quorum):
- RED: batch-20260609T023452Z-68aa et al — 5/5 agents fail
- GREEN: cost-spec-plan-duplication-claude-20260609T234142Z-9625 pass
(plan: "this plan does not restate them" + spec cited by path;
both docs in docs/superpowers/)
- Canary: triggering-writing-plans-claude pass (skill still fires)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The subagent review loop (dispatching a fresh agent to review plans/specs)
doubled execution time (~25 min overhead) without measurably improving plan
quality. Regression testing across 5 versions (v3.6.0 through v5.0.4) with
5 trials each showed identical plan sizes, task counts, and quality scores
regardless of whether the review loop ran.
Changes:
- writing-plans: Replace subagent Plan Review Loop with inline Self-Review
checklist (spec coverage, placeholder scan, type consistency)
- writing-plans: Add explicit "No Placeholders" section listing plan failures
(TBD, vague descriptions, undefined references, "similar to Task N")
- brainstorming: Replace subagent Spec Review Loop with inline Spec Self-Review
(placeholder scan, internal consistency, scope check, ambiguity check)
- Both skills now use "look at it with fresh eyes" framing
Testing: 5 trials with the new skill show self-review catches 3-5 real bugs
per run (spawn positions, API mismatches, seed bugs, grid indexing) in ~30s
instead of ~25 min. Remaining defects are comparable to the subagent approach.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove chunk-based plan review in favor of single whole-plan review
- Add Calibration sections to both reviewer prompts so only serious
issues block approval
- Reduce max review iterations from 5 to 3
- Streamline reviewer checklists (spec: 7→5, plan: 7→4 categories)
Subagents should never inherit the parent session's context or history.
The dispatcher constructs exactly what each subagent needs, keeping
both sides focused: the subagent on its task, the controller on
coordination.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The spec review loop (dispatch spec-document-reviewer subagent, iterate
until approved) existed in the prose "After the Design" section but was
missing from both the checklist and the process flow diagram. Since agents
follow the diagram and checklist more reliably than prose, the spec review
step was being skipped entirely.
Added step 7 (spec review loop) to the checklist and a corresponding
"Spec review loop" → "Spec review passed?" node pair to the dot graph.
Tested with claude --plugin-dir and claude-session-driver: worker now
correctly dispatches the spec-document-reviewer subagent after writing
the design doc and before presenting to the user for review.
Fixes#677.
After the spec review loop passes, the skill now asks the user to review
the written spec file before invoking writing-plans. This prevents the
agent from racing ahead to implementation planning without giving the
user a chance to read and adjust the written document.
Fixes#565
Brainstorming now assesses whether a project is too large for a single
spec and helps decompose into sub-projects. Scope check is inline in
the understanding phase (testing showed it was skipped as a separate step).
Spec reviewer also checks scope. Writing-plans has a backstop.
Brainstorming skill now offers an optional browser-based visual companion
for questions involving visual decisions (mockups, layouts, diagrams).
The companion is a tool, not a mode — each question is evaluated for
whether browser or terminal is more appropriate.
Includes visual-companion.md progressive disclosure guide with server
workflow, screen authoring patterns, and feedback collection.
Co-Authored-By: Drew Ritter <drew@ritter.dev>
The brainstorming skill described a process but didn't enforce it. Models
would skip the design phase and jump straight to implementation skills
like frontend-design, or collapse the entire brainstorming process into
a single text block.
Changes to brainstorming skill:
- Add HARD-GATE: no implementation until design is approved
- Add explicit checklist that maps to task items
- Add graphviz process flow with writing-plans as terminal state
- Add anti-pattern callout for "too simple to need a design"
- Scale design sections by section complexity, not project complexity
- Make writing-plans the only valid next skill after brainstorming
Changes to using-superpowers skill:
- Add EnterPlanMode intercept to workflow graph
- Route plan mode attempts through brainstorming skill instead
Tested with claude -p --plugin-dir across three variants (no skill,
original skill, updated skill) to verify behavioral compliance.
- Update brainstorming description to use imperative "You MUST use this"
- Clarify trigger: "before any creative work - creating features, building
components, adding functionality, or modifying behavior"
- Add Skill Priority section to using-superpowers to ensure process skills
(brainstorming, debugging) are invoked before implementation skills
Remove heavyweight 6-phase process with formal checklists and return to
conversational approach:
- Natural dialogue instead of structured phases
- One question at a time without rigid progression
- 200-300 word design sections with validation
- Keep documentation and implementation handoff
- Remove AskUserQuestion tool requirements and complex flowcharts
This aligns with the original spec: help turn ideas into designs through
collaborative questioning, then present design in small sections.
Applied Strunk's "Elements of Style" principles:
- Rule 13: Omitted needless words (removed "already", "genuinely", etc.)
- Rule 11: Converted negative to positive form ("don't ask" → "ask only when")
- Rule 10: Used active voice where appropriate
- Rule 15: Improved parallel construction in lists
- General: Made language more direct and concrete
Changes maintain the skill's functionality while improving readability.
The old brainstorming command included writing the design document
before handing off to implementation planning. This was lost when
the command was converted to a skill.
Added Phase 4: Design Documentation to write the validated design
to docs/plans/YYYY-MM-DD-<topic>.md before proceeding to worktree
setup and planning.
Tested with subagent to verify design document is written and
committed even under time pressure.
- Add explicit guidance to use AskUserQuestion in Phase 1 (Understanding)
- Add explicit guidance to use AskUserQuestion in Phase 2 (Exploration)
- Add concrete examples showing how to structure questions with options
- Add "Question Patterns" section explaining when to use AskUserQuestion vs open-ended
- Update Quick Reference table to include Tool Usage column
- Update Key Principles to mention structured choices with AskUserQuestion
Benefits:
- Makes it clear when to use structured vs open-ended questions
- Provides concrete examples for effective use of AskUserQuestion
- Helps present options with clear trade-offs
- 156 lines (well under 500-line Anthropic recommendation)
Update all skill references to use explicit requirement markers:
- REQUIRED BACKGROUND: For prerequisite understanding
- REQUIRED SUB-SKILL: For mandatory workflow dependencies
- Complementary skills: For optional but helpful related skills
Changes:
- Remove old path format (skills/collaboration/X → X)
- Add explicit "REQUIRED" markers to make dependencies clear
- Update Integration sections with categorized skill relationships
- Fix non-existent skill references
- Update cross-reference documentation in writing-skills
This makes it immediately clear which skills MUST be used vs optional references,
helping Claude understand and comply with skill dependencies.
- Fix description: correct grammar and use third-person voice
- Add Quick Reference table for easy scanning
- Add copyable checklist for tracking progress through phases
- Add decision flowchart for when to revisit earlier phases
- Convert "Remember" section to structured Key Principles table
- Remove references to non-existent related skills
Follows Anthropic patterns:
- Workflow with checklist format
- Quick reference table at top
- Appropriate use of flowchart for decision points
- Scannable table format for principles
- 108 lines (well under 500-line recommendation)
- Update all 20 skill frontmatter names to match their directory names in lowercase
- Fix defense-in-depth name (was Defense-in-Depth-Validation)
- Fix receiving-code-review name (was Code-Review-Reception)
- Update all skill announcements and cross-references to use lowercase names
- Update commands redirects to reference lowercase skill names
Ensures consistent naming: skill directory names, frontmatter names, and documentation
references all use lowercase kebab-case format (e.g., brainstorming, test-driven-development)
