Skip to content

An agentic skills framework & software development methodology that works.

Add design documentation phase to brainstorming skill

Jesse Vincent9597f088c43f
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md
index a8e46116b..2c674ceec 100644
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -20,8 +20,9 @@ Transform rough ideas into fully-formed designs through structured questioning a
| **1. Understanding** | Ask questions (one at a time) | AskUserQuestion for choices | Purpose, constraints, criteria |
| **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
| **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
-| **4. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment |
-| **5. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown |
+| **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ |
+| **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment |
+| **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown |
## The Process
@@ -32,8 +33,9 @@ Brainstorming Progress:
- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
- [ ] Phase 3: Design Presentation (design validated in sections)
-- [ ] Phase 4: Worktree Setup (if implementing)
-- [ ] Phase 5: Planning Handoff (if implementing)
+- [ ] Phase 4: Design Documentation (design written to docs/plans/)
+- [ ] Phase 5: Worktree Setup (if implementing)
+- [ ] Phase 6: Planning Handoff (if implementing)
```
### Phase 1: Understanding
@@ -72,14 +74,21 @@ Options:
- Ask after each section: "Does this look right so far?" (open-ended)
- Use open-ended questions here to allow freeform feedback
-### Phase 4: Worktree Setup (for implementation)
+### Phase 4: Design Documentation
+After design is validated, write it to a permanent document:
+- **File location:** `docs/plans/YYYY-MM-DD-<topic>.md` (use actual date and descriptive topic)
+- **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
+- **Content:** Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation
+- Commit the design document to git before proceeding
+
+### Phase 5: Worktree Setup (for implementation)
When design is approved and implementation will follow:
- Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."
- **REQUIRED SUB-SKILL:** Use using-git-worktrees
- Follow that skill's process for directory selection, safety verification, and setup
- Return here when worktree ready
-### Phase 5: Planning Handoff
+### Phase 6: Planning Handoff
Ask: "Ready to create the implementation plan?"
When your human partner confirms (any affirmative response):