diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 06cd0a21..f503894d 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -26,7 +26,7 @@ You MUST create a task for each of these items and complete them in order: 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria 4. **Propose 2-3 approaches** — with trade-offs and your recommendation 5. **Present design** — in sections scaled to their complexity, get user approval after each section -6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit +6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit (exactly this path — not `docs/specs/`) 7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below) 8. **User reviews written spec** — ask user to review the spec file before proceeding 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan @@ -109,6 +109,7 @@ 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/` - (User preferences for spec location override this default) - 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 847412ec..caba61d9 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -7,10 +7,12 @@ description: Use when you have a spec or requirements for a multi-step task, bef ## Overview -Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. +Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to execute: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. 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. + **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. @@ -53,6 +55,8 @@ 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] + **Architecture:** [2-3 sentences about approach] **Tech Stack:** [Key technologies/libraries]