diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index f503894d..e0cde156 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -110,7 +110,7 @@ digraph brainstorming { - 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/` - - (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 diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index caba61d9..308b3e23 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -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--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--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