first commit

skills/brainstorming/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: brainstorming
+description: Clarify what to build before planning or implementation by exploring intent, constraints, trade-offs, and success criteria. Use when requests are ambiguous, have multiple valid interpretations, include phrases like "let's brainstorm" or "help me think through", or when feature scope needs refinement before writing an implementation plan.
+---
+
+# Brainstorming
+
+Guide collaborative brainstorming sessions that define WHAT to build before HOW to build it. Keep output short, decision-oriented, and validated with the user at each step.
+
+## Phase 0: Assess Clarity
+
+Decide whether brainstorming is necessary before asking discovery questions.
+
+Signals to skip brainstorming and proceed:
+- Requirements include concrete acceptance criteria.
+- Expected behavior and boundaries are explicit.
+- Task is a straightforward bug fix or well-scoped change.
+
+If clarity is already high, say:
+- "Requirements look clear. Proceed directly to planning or implementation."
+
+## Phase 1: Understand the Idea
+
+Ask one question at a time. Prefer multiple-choice when natural options exist.
+
+Question order:
+1. Purpose: problem and motivation.
+2. Users: who uses it and in what context.
+3. Constraints: technical, timeline, dependencies.
+4. Success: how "good" is measured.
+5. Edge cases: failures, exclusions, non-goals.
+6. Existing patterns: similar feature to follow.
+
+Validate assumptions explicitly:
+- "I assume users are authenticated. Correct?"
+
+Exit this phase when the request is clear or the user says "proceed".
+
+## Phase 2: Explore Approaches
+
+Provide 2-3 options with explicit trade-offs and a recommendation.
+
+Use this structure:
+
+### Approach A: <Name>
+<2-3 sentence summary>
+
+Pros:
+- <benefit>
+- <benefit>
+
+Cons:
+- <trade-off>
+- <trade-off>
+
+Best when:
+- <condition>
+
+Apply YAGNI:
+- Prefer the simplest approach that solves the current problem.
+- Defer speculative complexity.
+
+## Phase 3: Capture Decisions
+
+Write a concise brainstorm note to:
+- `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
+
+Use this format:
+
+```markdown
+---
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+---
+
+# <Topic Title>
+
+## What We're Building
+<1-2 short paragraphs>
+
+## Why This Approach
+<brief comparison and rationale>
+
+## Key Decisions
+- <decision>: <rationale>
+- <decision>: <rationale>
+
+## Open Questions
+- <unresolved item>
+
+## Next Steps
+-> `/workflows:plan`
+```
+
+## Phase 4: Handoff
+
+Offer exactly one clear next action:
+1. Proceed to planning.
+2. Refine assumptions.
+3. Pause and resume later.
+
+Keep each response section short (about 200-300 words max), then confirm alignment:
+- "Does this match your intent?"
+- "Any adjustments before we continue?"