Compare commits

..

4 Commits

Author SHA1 Message Date
Drew Ritter
81874ec5b1 refine(skills): staff-review round — trim reference rule, close executing-plans spec gap
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>
2026-06-10 18:24:57 -07:00
Drew Ritter
49a91fd404 harden(skills): no-spec branch cannot be used to skip writing the spec
Eval-caught regression: the no-spec branch added to the **Spec:**
header gave the agent a sanctioned path to skip the spec doc entirely
("avoiding duplication by skipping the spec" —
cost-spec-plan-duplication-claude-20260610T213934Z-8e5b, fail). The
branch is now scoped: if brainstorming happened the spec exists and
must be cited; "none — requirements:" applies only when requirements
arrived conversationally and no spec doc was ever produced. The
reference-discipline paragraph states the same rule up front.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-10 14:49:01 -07:00
Drew Ritter
64d194a08e harden(skills): close paraphrase/no-spec/preference loopholes in plan reference rule
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>
2026-06-10 14:34:56 -07:00
Drew Ritter
fa07663322 fix(skills): plans reference the spec instead of restating it (SUP-333 #1)
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>
2026-06-09 16:52:21 -07:00
5 changed files with 4 additions and 10 deletions

2
evals

Submodule evals updated: f8e5a9949f...ff3ee83f94

View File

@@ -86,10 +86,6 @@ digraph process {
} }
``` ```
## Spec Context
If the plan's header cites a spec (`**Spec:** <path>`), read it once during plan extraction. Plans reference requirements rather than restating them — when a task cites a spec section, paste that section's text into the implementer and spec-reviewer prompts along with the task text. Implementer subagents never read the spec file themselves; the spec reviewer may additionally read it at the cited path (its prompt says so).
## Model Selection ## Model Selection
Use the least powerful model that can handle each role to conserve cost and increase speed. Use the least powerful model that can handle each role to conserve cost and increase speed.

View File

@@ -12,8 +12,6 @@ Subagent (general-purpose):
[FULL TEXT of task from plan - paste it here, don't make subagent read file] [FULL TEXT of task from plan - paste it here, don't make subagent read file]
[If the task cites spec sections, paste the cited sections' text here too]
## Context ## Context
[Scene-setting: where this fits, dependencies, architectural context] [Scene-setting: where this fits, dependencies, architectural context]

View File

@@ -12,7 +12,7 @@ Subagent (general-purpose):
## What Was Requested ## What Was Requested
[FULL TEXT of task requirements, including the text of any spec sections the task cites] [FULL TEXT of task requirements]
## What Implementer Claims They Built ## What Implementer Claims They Built
@@ -28,7 +28,7 @@ Subagent (general-purpose):
git diff [BASE_SHA]..[HEAD_SHA] git diff [BASE_SHA]..[HEAD_SHA]
``` ```
Only read files in this diff. Do not crawl the broader codebase. (One exception: if the requirements cite a spec document, you may read that spec at its cited path.) Only read files in this diff. Do not crawl the broader codebase.
## Read-Only Review ## Read-Only Review

View File

@@ -149,7 +149,7 @@ After saving the plan, offer execution choice:
**If Subagent-Driven chosen:** **If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development - **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:** **If Inline Execution chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans - **REQUIRED SUB-SKILL:** Use superpowers:executing-plans