rogee/superpowers
1
0
Fork 0
mirror of https://github.com/obra/superpowers.git synced 2026-06-11 21:29:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

harden(skills): close paraphrase/no-spec/preference loopholes in plan reference rule

Browse Source 
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>
This commit is contained in:
Drew Ritter
2026-06-10 14:34:56 -07:00
parent fa07663322
commit 64d194a08e
2 changed files with 4 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
skills/brainstorming/SKILL.md
View File

@@ -110,7 +110,7 @@ digraph brainstorming {
- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
- The `docs/superpowers/` prefix is the convention; do not shorten it to `docs/specs/`
- (User preferences for spec location override this default)
- (An explicit user instruction overrides this default; an existing differently-named docs directory does not)
- Use elements-of-style:writing-clearly-and-concisely skill if available
- Commit the design document to git

6
skills/writing-plans/SKILL.md
View File

@@ -11,7 +11,7 @@ Write comprehensive implementation plans assuming the engineer has zero context
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
**Plans reference the spec; they never restate it.** The spec owns the WHAT and WHY — requirements, acceptance criteria, design decisions. The plan owns the HOW — tasks, files, code, commands. Cite the spec by path in the header and by section where a task needs context. Re-deriving spec content inline doubles the documents and lets them drift apart. "Zero context" means the engineer can execute each step mechanically; it does not mean the plan repeats what the spec already says — they can read the spec at the cited path.
**Plans reference the spec; they never restate, paraphrase, or summarize it.** The spec owns the WHAT and WHY — requirements, acceptance criteria, design decisions. The plan owns the HOW — tasks, files, code, commands. Cite the spec by path in the header and by section where a task needs context. Repetition WITHIN the plan (code, commands — see No Placeholders) is required; copying FROM the spec is not: if a step seems to need a requirement's prose to be executable, the step is under-specified — turn the requirement into a concrete action. The spec at the cited path is the single source of truth; snapshotting its content into the plan does not prevent drift, it hides drift. "Zero context" means the engineer can execute each step mechanically; it does not mean the plan repeats what the spec already says.
**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
@@ -55,7 +55,7 @@ This structure informs the task decomposition. Each task should produce self-con
**Goal:** [One sentence describing what this builds]
**Spec:** [Path to the spec doc, e.g. `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — requirements and design decisions live there; do not restate them here]
**Spec:** [Path to the spec doc, e.g. `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — requirements and design decisions live there; do not restate them here. If no spec doc exists, write "none — requirements:" and state them once here, not per task]
**Architecture:** [2-3 sentences about approach]
@@ -149,7 +149,7 @@ After saving the plan, offer execution choice:
**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Fresh subagent per task + two-stage review
- Fresh subagent per task + two-stage review (review fanout scales with the change — see that skill's Proportionality rule)
**If Inline Execution chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans