diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 2fd19ba1e..ac21f9d61 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -1,54 +1,61 @@ --- name: brainstorming -description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." +description: | + Collaborative design exploration before implementation. Use when asked to + "brainstorm", "design a feature", "explore ideas", "plan before coding", + or before any creative work like creating features, building components, + or adding functionality. --- # Brainstorming Ideas Into Designs -## Overview +Transform ideas into validated designs through structured dialogue. Ask one question at a time, present designs in 200-300 word sections, and validate incrementally. -Help turn ideas into fully formed designs and specs through natural collaborative dialogue. +## Workflow -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. +### Phase 1: Understand Context -## The Process +1. Review current project state (files, docs, recent commits) +2. Ask one question per message to refine the idea +3. Prefer multiple-choice questions when possible +4. Focus on: purpose, constraints, success criteria -**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 +### Phase 2: Explore Approaches -**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 +5. Propose 2-3 approaches with trade-offs +6. Lead with recommended option and explain reasoning +7. Confirm direction before proceeding -**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 +### Phase 3: Present Design -## After the Design +8. Present design in 200-300 word sections +9. After each section, ask: "Does this look right so far?" +10. Cover: architecture, components, data flow, error handling, testing +11. Revisit earlier sections if clarification needed -**Documentation:** -- Write the validated design to `docs/plans/YYYY-MM-DD--design.md` -- Use elements-of-style:writing-clearly-and-concisely skill if available -- Commit the design document to git +### Phase 4: Document -**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 +12. Write validated design to `docs/plans/YYYY-MM-DD--design.md` + - See [references/design-template.md](references/design-template.md) for structure +13. Use elements-of-style:writing-clearly-and-concisely skill if available +14. Commit the design document to git -## Key Principles +### Phase 5: Handoff (Optional) -- **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 +15. Ask: "Ready to set up for implementation?" +16. Use superpowers:using-git-worktrees for isolated workspace +17. Use superpowers:writing-plans for detailed implementation plan + +## Guidelines + +- **One question per message** - Avoid overwhelming with multiple questions +- **Multiple-choice preferred** - Easier to answer than open-ended +- **YAGNI ruthlessly** - Remove unnecessary features from designs +- **Validate incrementally** - Check understanding after each section + +## Reference Files + +| File | Purpose | +|------|---------| +| [references/design-template.md](references/design-template.md) | Design document structure | +| [references/example-session.md](references/example-session.md) | Sample brainstorming dialogue | diff --git a/skills/brainstorming/references/design-template.md b/skills/brainstorming/references/design-template.md new file mode 100644 index 000000000..8b7861dd6 --- /dev/null +++ b/skills/brainstorming/references/design-template.md @@ -0,0 +1,100 @@ +# Design Document Template + +Use this structure for design documents written to `docs/plans/`. + +## Filename Format + +``` +docs/plans/YYYY-MM-DD--design.md +``` + +Example: `docs/plans/2025-01-15-user-authentication-design.md` + +--- + +## Template + +```markdown +# [Feature Name] Design + +**Date:** YYYY-MM-DD +**Status:** Draft | Validated | Implemented +**Author:** [Name or "AI-assisted"] + +## Summary + +[2-3 sentences describing what this design accomplishes] + +## Problem Statement + +[What problem does this solve? Why is it needed?] + +## Requirements + +### Functional Requirements +- [ ] Requirement 1 +- [ ] Requirement 2 + +### Non-Functional Requirements +- [ ] Performance: [specific metric] +- [ ] Security: [considerations] + +## Proposed Solution + +### Architecture Overview + +[High-level description of the approach] + +### Components + +| Component | Responsibility | +|-----------|---------------| +| ComponentA | Description | +| ComponentB | Description | + +### Data Flow + +[Describe how data moves through the system] + +### Error Handling + +[How errors are detected, reported, and recovered] + +## Alternatives Considered + +### Option A: [Name] +- **Pros:** ... +- **Cons:** ... + +### Option B: [Name] +- **Pros:** ... +- **Cons:** ... + +**Decision:** Selected [Option] because [reasoning] + +## Testing Strategy + +- Unit tests: [what to test] +- Integration tests: [what to test] +- Edge cases: [list] + +## Implementation Plan + +1. Step 1 +2. Step 2 +3. Step 3 + +## Open Questions + +- [ ] Question 1 +- [ ] Question 2 +``` + +--- + +## Tips + +- Keep each section focused and concise +- Use diagrams when architecture is complex +- Link to relevant code files or documentation +- Update status as design progresses through validation diff --git a/skills/brainstorming/references/example-session.md b/skills/brainstorming/references/example-session.md new file mode 100644 index 000000000..688de0147 --- /dev/null +++ b/skills/brainstorming/references/example-session.md @@ -0,0 +1,112 @@ +# Example Brainstorming Session + +Demonstrates the brainstorming workflow with a real scenario. + +--- + +## Scenario: Adding User Notifications + +**User:** I want to add notifications to my app. + +--- + +### Phase 1: Understand Context + +**Claude:** I see this is a React/Node.js web application with PostgreSQL. Before diving into notifications, let me understand the scope: + +What types of events should trigger notifications? + +A) User actions (new messages, mentions, replies) +B) System events (maintenance, updates, errors) +C) Both user and system events +D) Something else + +**User:** A - just user actions for now. + +**Claude:** Good, focusing on user-triggered notifications. What's the primary delivery channel? + +A) In-app notifications only (badge, dropdown) +B) Email notifications only +C) Both in-app and email +D) Push notifications (mobile/browser) + +**User:** A - in-app only. + +--- + +### Phase 2: Explore Approaches + +**Claude:** For in-app notifications, here are three approaches: + +**Recommended: Polling with Smart Caching** +- Client polls every 30 seconds +- Server caches unread count in Redis +- Simple to implement, good enough for most apps +- Trade-off: Slight delay (up to 30s) + +**Alternative 1: WebSockets** +- Real-time updates +- More complex infrastructure +- Better for chat-heavy apps + +**Alternative 2: Server-Sent Events** +- One-way real-time +- Simpler than WebSockets +- Limited browser connection pool + +I recommend polling for this use case. The 30-second delay is acceptable for user action notifications, and it avoids WebSocket complexity. Agree? + +**User:** Yes, polling sounds right. + +--- + +### Phase 3: Present Design + +**Claude:** Here's the first section - the data model: + +### Notifications Table +```sql +CREATE TABLE notifications ( + id UUID PRIMARY KEY, + user_id UUID REFERENCES users(id), + type VARCHAR(50) NOT NULL, + title VARCHAR(255) NOT NULL, + body TEXT, + read_at TIMESTAMP, + created_at TIMESTAMP DEFAULT NOW() +); +``` + +The `type` field allows filtering (mentions, replies, etc.). The `read_at` timestamp tracks read status while preserving when it was read. + +Does this look right so far? + +**User:** Yes, but add a `link` field for navigation. + +**Claude:** Good catch. Adding `link VARCHAR(500)` for the target URL. Next section - the API endpoints... + +--- + +### Phase 4: Document + +**Claude:** Design validated. Writing to `docs/plans/2025-01-15-user-notifications-design.md`. + +[Commits design document] + +--- + +### Phase 5: Handoff + +**Claude:** Ready to set up for implementation? I can create a worktree and detailed implementation plan. + +**User:** Yes, let's do it. + +--- + +## Key Patterns Demonstrated + +1. **One question per message** - Each question focused on single decision +2. **Multiple-choice options** - Made decisions easier +3. **Recommendation with reasoning** - Led with preferred option +4. **Incremental validation** - Checked after each design section +5. **Flexibility** - Incorporated user's `link` field suggestion