Pārlūkot izejas kodu

Simplify brainstorming skill to match original vision

Remove heavyweight 6-phase process with formal checklists and return to
conversational approach:
- Natural dialogue instead of structured phases
- One question at a time without rigid progression
- 200-300 word design sections with validation
- Keep documentation and implementation handoff
- Remove AskUserQuestion tool requirements and complex flowcharts

This aligns with the original spec: help turn ideas into designs through
collaborative questioning, then present design in small sections.
Jesse Vincent 10 mēneši atpakaļ
vecāks
revīzija
8e38ab86dc
1 mainītis faili ar 39 papildinājumiem un 160 dzēšanām
  1. 39 160
      skills/brainstorming/SKILL.md

+ 39 - 160
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