From 81874ec5b1be535ce807d65a2a376896bd8dbc1b Mon Sep 17 00:00:00 2001 From: Drew Ritter Date: Wed, 10 Jun 2026 18:24:57 -0700 Subject: [PATCH] =?UTF-8?q?refine(skills):=20staff-review=20round=20?= =?UTF-8?q?=E2=80=94=20trim=20reference=20rule,=20close=20executing-plans?= =?UTF-8?q?=20spec=20gap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- skills/brainstorming/SKILL.md | 1 - skills/executing-plans/SKILL.md | 2 +- skills/writing-plans/SKILL.md | 6 +++--- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index e0cde156..15b6fd32 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -109,7 +109,6 @@ digraph brainstorming { **Documentation:** - Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD--design.md` - - The `docs/superpowers/` prefix is the convention; do not shorten it to `docs/specs/` - (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 diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 78d88540..da10abac 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -16,7 +16,7 @@ Load plan, review critically, execute all tasks, report when complete. ## The Process ### Step 1: Load and Review Plan -1. Read plan file +1. Read plan file, and the spec it cites in its `**Spec:**` header (plans reference requirements rather than restating them) 2. Review critically - identify any questions or concerns about the plan 3. If concerns: Raise them with your human partner before starting 4. If no concerns: Create todos for the plan items and proceed diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index f3ec5003..f33f905a 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -11,14 +11,14 @@ 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, paraphrase, or summarize it.** Reference discipline means the plan points at the spec — never that you skip writing the spec: if the workflow produced one (brainstorming did), it exists and the plan cites 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. +**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 it by path in the header and by section where a task needs context. Reference discipline never means skipping the spec: if brainstorming produced one, it exists and the plan cites it. No Placeholders still requires repeating code and commands WITHIN the plan; copying FROM the spec is different: a step that needs a requirement's prose is under-specified — turn it into a concrete action. Snapshotting spec text into the plan hides drift, not prevents it. "Zero context" means each step is mechanically executable, not that the plan repeats the spec. **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." **Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time. **Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-.md` -- (User preferences for plan location override this default) +- (An explicit user instruction overrides this default; an existing differently-named docs directory does not) ## Scope Check @@ -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--design.md` — requirements and design decisions live there; do not restate them here. If brainstorming happened, the spec doc exists and this line cites it — never skip writing the spec to avoid duplication; reference it instead. Only when requirements arrived conversationally and no spec doc was ever produced: write "none — requirements:" and state them once here, not per task] +**Spec:** [Path to the spec doc, e.g. `docs/superpowers/specs/YYYY-MM-DD--design.md` — requirements and design decisions live there; do not restate them here. Only if no spec doc exists (requirements arrived conversationally; brainstorming never ran): write "none — requirements:" and state them once here, not per task] **Architecture:** [2-3 sentences about approach]