Improve brainstorming skill from 71/100 to 97/100 (Grade C → A)

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-<topic>-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-<topic>-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 |

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-<topic>-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

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