An agentic skills framework & software development methodology that works.
Simplify brainstorming skill to match original vision
Jesse Vincent8e38ab86dcd4
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.mdindex 60bae4e71..b117ed92f 100644--- a/skills/brainstorming/SKILL.md+++ b/skills/brainstorming/SKILL.md@@ -1,175 +1,54 @@---name: brainstorming-description: Use when creating or developing anything, before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation+description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes---# Brainstorming Ideas Into Designs## Overview-Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.-**Core principle:** Research first, ask targeted questions to fill gaps, explore alternatives, present design incrementally for validation.--**Announce at start:** "I'm using the brainstorming skill to refine your idea into a design."--## Quick Reference--| Phase | Key Activities | Tool Usage | Output |-|-------|---------------|------------|--------|-| **Prep: Autonomous Recon** | Inspect repo/docs/commits, form initial model | Native tools (ls, cat, git log, etc.) | Draft understanding to confirm |-| **1. Understanding** | Share findings, ask only for missing context | AskUserQuestion for real decisions | Purpose, constraints, criteria (confirmed) |-| **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. 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 |+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.## The Process-Copy this checklist to track progress:--```-Brainstorming Progress:-- [ ] Prep: Autonomous Recon (repo/docs/commits reviewed, initial model shared)-- [ ] 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: Design Documentation (design written to docs/plans/)-- [ ] Phase 5: Worktree Setup (if implementing)-- [ ] Phase 6: Planning Handoff (if implementing)-```--### Prep: Autonomous Recon-- Use existing tools (file browsing, docs, git history, tests) to understand current project state before asking anything.-- Form your draft model: what problem you're solving, what artifacts exist, and what questions remain.-- Start the conversation by sharing that model: "Based on exploring the project state, docs, working copy, and recent commits, here's how I think this should work…"-- Ask follow-up questions only for information you cannot infer from available materials.--### Phase 1: Understanding-- Share your synthesized understanding first, then invite corrections or additions.-- Ask one focused question at a time, only for gaps you cannot close yourself.-- **Use AskUserQuestion tool** only when you need the human to make a decision among real alternatives.-- Gather: Purpose, constraints, success criteria (confirmed or amended by your partner)--**Example summary + targeted question:**-```-Based on the README and yesterday's commit, we're expanding localization to dashboard and billing emails; admin console is still untouched. Only gap I see is whether support responses need localization in this iteration. Did I miss anything important?-```--### Phase 2: Exploration-- Propose 2-3 different approaches-- For each: Core architecture, trade-offs, complexity assessment, and your recommendation-- **Use AskUserQuestion tool** to present approaches when you truly need a judgement call-- Lead with the option you prefer and explain why; invite disagreement if your partner sees it differently-- Own prioritization: if the repo makes priorities clear, state them and proceed rather than asking--**Example using AskUserQuestion:**-```-Question: "Which architectural approach should we use?"-Options:- - "Direct API calls with retry logic" (simple, synchronous, easier to debug) ← recommended for current scope- - "Event-driven with message queue" (scalable, complex setup, eventual consistency)- - "Hybrid with background jobs" (balanced, moderate complexity, best of both)--I recommend the direct API approach because it matches existing patterns and minimizes new infrastructure. Let me know if you see a blocker that pushes us toward the other options.-```--### Phase 3: Design Presentation-- Present in coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious-- Cover: Architecture, components, data flow, error handling, testing-- Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect."-- Use open-ended questions to allow freeform feedback-- Assume ownership and proceed unless your partner redirects you--### Phase 4: Design Documentation-After validating the design, write it to a permanent document:-- **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.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 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 superpowers:using-git-worktrees-- Follow that skill's process for directory selection, safety verification, and setup-- Return here when worktree ready--### Phase 6: Planning Handoff-Ask: "Ready to create the implementation plan?"--When your human partner confirms (any affirmative response):-- Announce: "I'm using the writing-plans skill to create the implementation plan."-- **REQUIRED SUB-SKILL:** Use superpowers:writing-plans-- Create detailed plan in the worktree--## Question Patterns--### When to Use AskUserQuestion Tool--**Use AskUserQuestion when:**-- You need your partner to make a judgement call among real alternatives-- You have a recommendation and can explain why it’s your preference-- Prioritization is ambiguous and cannot be inferred from existing materials--**Best practices:**-- State your preferred option and rationale inside the question so your partner can agree or redirect-- If you know the answer from repo/docs, state it as fact and proceed—no question needed-- When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner--### When to Use Open-Ended Questions--**Use open-ended questions for:**-- Phase 3: Design validation ("Does this look right so far?")-- When you need detailed feedback or explanation-- When partner should describe their own requirements-- When structured options would limit creative input--Frame them to confirm or expand your current understanding rather than reopening settled topics.--**Example decision flow:**-- "What authentication method?" → Use AskUserQuestion (2-4 options)-- "Does this design handle your use case?" → Open-ended (validation)--## When to Revisit Earlier Phases--```dot-digraph revisit_phases {- rankdir=LR;- "New constraint revealed?" [shape=diamond];- "Partner questions approach?" [shape=diamond];- "Requirements unclear?" [shape=diamond];- "Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"];- "Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"];- "Continue forward" [shape=box, style=filled, fillcolor="#ccffcc"];-- "New constraint revealed?" -> "Return to Phase 1" [label="yes"];- "New constraint revealed?" -> "Partner questions approach?" [label="no"];- "Partner questions approach?" -> "Return to Phase 2" [label="yes"];- "Partner questions approach?" -> "Requirements unclear?" [label="no"];- "Requirements unclear?" -> "Return to Phase 1" [label="yes"];- "Requirements unclear?" -> "Continue forward" [label="no"];-}-```--**You can and should go backward when:**-- Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1-- Validation shows fundamental gap in requirements → Return to Phase 1-- Partner questions approach during Phase 3 → Return to Phase 2-- Something doesn't make sense → Go back and clarify--**Avoid forcing forward linearly** when going backward would give better results.+**Understanding the idea:**+- Check out the current project state first (files, docs, recent commits)+- Ask questions one at a time to refine the idea+- Prefer multiple choice questions when possible, but open-ended is fine too+- Only one question per message - if a topic needs more exploration, break it into multiple questions+- Focus on understanding: purpose, constraints, success criteria++**Exploring approaches:**+- Propose 2-3 different approaches with trade-offs+- Present options conversationally with your recommendation and reasoning+- Lead with your recommended option and explain why++**Presenting the design:**+- Once you believe you understand what you're building, present the design+- Break it into sections of 200-300 words+- Ask after each section whether it looks right so far+- Cover: architecture, components, data flow, error handling, testing+- Be ready to go back and clarify if something doesn't make sense++## After the Design++**Documentation:**+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`+- Use elements-of-style:writing-clearly-and-concisely skill if available+- Commit the design document to git++**Implementation (if continuing):**+- Ask: "Ready to set up for implementation?"+- Use superpowers:using-git-worktrees to create isolated workspace+- Use superpowers:writing-plans to create detailed implementation plan## Key Principles-| Principle | Application |-|-----------|-------------|-| **One question at a time** | Phase 1: Single targeted question only for gaps you can’t close yourself |-| **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs |-| **YAGNI ruthlessly** | Remove unnecessary features from all designs |-| **Explore alternatives** | Always propose 2-3 approaches before settling |-| **Incremental validation** | Present design in sections, validate each |-| **Flexible progression** | Go backward when needed - flexibility > rigidity |-| **Own the initiative** | Recommend priorities and next steps; ask if you should proceed only when requirements conflict |-| **Announce usage** | State skill usage at start of session |+- **One question at a time** - Don't overwhelm with multiple questions+- **Multiple choice preferred** - Easier to answer than open-ended when possible+- **YAGNI ruthlessly** - Remove unnecessary features from all designs+- **Explore alternatives** - Always propose 2-3 approaches before settling+- **Incremental validation** - Present design in sections, validate each+- **Be flexible** - Go back and clarify when something doesn't make sense