From a6ce936ac1437cca2386b948be846e9e4b8b4ac7 Mon Sep 17 00:00:00 2001 From: Drew Ritter Date: Wed, 10 Jun 2026 14:36:49 -0700 Subject: [PATCH] harden(skills): SDD proportionality resists over-use; pipeline consumes cited specs Adversarial + consistency review findings (B1, B2, B3, B5, F1): - Red Flags line read literally licensed skipping reviews on trivial tasks INSIDE multi-task plans; now states the only exception is a whole-plan trivial change and never-skip within multi-task plans. - "a one-line edit" example blessed one-line behavioral changes (e.g. adding "|| user.isOwner"); dropped. Trivial is now defined as a property of the diff (no logic/control-flow/behavior change), not of the plan's self-description. The "nothing for review to catch" justification proved too much; replaced with the cost argument. - "verify it" was undefined on the trivial path; now concrete (run tests/command, confirm output, verification-before-completion). - Flowchart diamond now matches the prose: "fully-specified" + "any doubt = no" (the failing agents execute the flowchart literally). - New Spec Context section + prompt-template updates: the controller reads the spec cited in the plan header and pastes cited sections into implementer/spec-reviewer prompts; the spec reviewer's diff-only rule gets a spec-document exception. Without this, the stack's reference-not-restate rule starves the SDD pipeline of requirements. Co-Authored-By: Claude Fable 5 --- skills/subagent-driven-development/SKILL.md | 16 ++++++++++------ .../implementer-prompt.md | 2 ++ .../spec-reviewer-prompt.md | 4 ++-- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 3590d392..962d8369 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -11,7 +11,7 @@ Execute plan by dispatching fresh subagent per task, with two-stage review after **Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration -**Proportionality:** Review fanout scales with the change. When the entire plan is one trivial, fully-specified mechanical change — a one-line edit, a log statement, a constant bump — implement it directly (or with a single implementer subagent), verify it, and commit. Skip the review subagents and the final reviewer: a diff with no room for interpretation has nothing for a spec or quality review to catch, and three dispatches for one line cost more than the change itself. When in doubt whether a change is trivial, it is not — run the full pipeline. Within a multi-task plan, run the full pipeline for every task regardless of size; this exception applies only when the whole plan is one trivial change. +**Proportionality:** Review fanout scales with the change. When the entire plan is one trivial, fully-specified mechanical change — a log statement, a constant bump, a typo fix — implement it directly (or with a single implementer subagent), verify it (run the relevant tests or command and confirm the output — superpowers:verification-before-completion applies), commit, and skip the review subagents and the final reviewer: three review dispatches for a one-line diff cost more than the change itself. Trivial is a property of the diff, not of the plan's description of itself: the diff changes no logic, control flow, or observable behavior beyond the literally stated value. When in doubt whether a change is trivial, it is not — run the full pipeline. Within a multi-task plan, run the full pipeline for every task regardless of size; this exception applies only when the whole plan is one trivial change. **Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it. @@ -63,16 +63,16 @@ digraph process { } "Read plan, extract all tasks with full text, note context, create todos" [shape=box]; - "Entire plan = one trivial mechanical change?" [shape=diamond]; + "Entire plan = one trivial, fully-specified mechanical change? (any doubt = no)" [shape=diamond]; "Implement directly, verify, commit (no review fanout)" [shape=box]; "More tasks remain?" [shape=diamond]; "Dispatch final code reviewer subagent for entire implementation" [shape=box]; "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; - "Read plan, extract all tasks with full text, note context, create todos" -> "Entire plan = one trivial mechanical change?"; - "Entire plan = one trivial mechanical change?" -> "Implement directly, verify, commit (no review fanout)" [label="yes — see Proportionality"]; + "Read plan, extract all tasks with full text, note context, create todos" -> "Entire plan = one trivial, fully-specified mechanical change? (any doubt = no)"; + "Entire plan = one trivial, fully-specified mechanical change? (any doubt = no)" -> "Implement directly, verify, commit (no review fanout)" [label="yes — see Proportionality"]; "Implement directly, verify, commit (no review fanout)" -> "Use superpowers:finishing-a-development-branch"; - "Entire plan = one trivial mechanical change?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="no"]; + "Entire plan = one trivial, fully-specified mechanical change? (any doubt = no)" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="no"]; "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?"; "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"]; "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)"; @@ -93,6 +93,10 @@ digraph process { } ``` +## Spec Context + +If the plan's header cites a spec (`**Spec:** `), 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. Subagents never read the spec file themselves. + ## Model Selection Use the least powerful model that can handle each role to conserve cost and increase speed. @@ -244,7 +248,7 @@ Done! **Never:** - Start implementation on main/master branch without explicit user consent -- Skip reviews (spec compliance OR code quality) on a non-trivial task — the Proportionality exception covers only a plan that is one trivial mechanical change +- Skip reviews — the only exception is a plan whose ENTIRE content is one trivial, fully-specified mechanical change (see Proportionality); within a multi-task plan, never skip reviews regardless of task size - Proceed with unfixed issues - Dispatch multiple implementation subagents in parallel (conflicts) - Make subagent read plan file (provide full text instead) diff --git a/skills/subagent-driven-development/implementer-prompt.md b/skills/subagent-driven-development/implementer-prompt.md index d9a32f70..083c542d 100644 --- a/skills/subagent-driven-development/implementer-prompt.md +++ b/skills/subagent-driven-development/implementer-prompt.md @@ -12,6 +12,8 @@ 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 — the plan references requirements rather than restating them] + ## Context [Scene-setting: where this fits, dependencies, architectural context] diff --git a/skills/subagent-driven-development/spec-reviewer-prompt.md b/skills/subagent-driven-development/spec-reviewer-prompt.md index 1cc84a76..5f74ed28 100644 --- 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] + [FULL TEXT of task requirements, including the text of any spec sections the task cites — the plan references requirements rather than restating them] ## 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. + 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.) ## Read-Only Review