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>
harden(skills): no-spec branch cannot be used to skip writing the spec
2026-06-30 14:39:04 +08:00 · 2026-06-10 18:24:57 -07:00 · 2026-06-10 14:49:01 -07:00 · 2026-06-10 14:34:56 -07:00 · 2026-06-09 16:52:21 -07:00
5 changed files with 4 additions and 10 deletions
--- a/2
+++ b/2
--- a/skills/subagent-driven-development/SKILL.md
+++ b/skills/subagent-driven-development/SKILL.md
@@ -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

 Use the least powerful model that can handle each role to conserve cost and increase speed.
--- a/skills/subagent-driven-development/implementer-prompt.md
+++ b/skills/subagent-driven-development/implementer-prompt.md
@@ -12,8 +12,6 @@ Subagent (general-purpose):

    [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

    [Scene-setting: where this fits, dependencies, architectural context]
--- a/skills/subagent-driven-development/spec-reviewer-prompt.md
+++ b/skills/subagent-driven-development/spec-reviewer-prompt.md
@@ -12,7 +12,7 @@ Subagent (general-purpose):

    ## 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

@@ -28,7 +28,7 @@ Subagent (general-purpose):
    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

--- a/skills/writing-plans/SKILL.md
+++ b/skills/writing-plans/SKILL.md
@@ -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
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