110 lines
3.4 KiB
Markdown
110 lines
3.4 KiB
Markdown
|
# Brainstorming Pattern
|
||
|
|
|
||
|
|
Required design refinement for non-trivial concepts before implementation.
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
|
||
|
|
Refine rough ideas into clear designs through drafting, self-critique, and trade-off surfacing. Prevents building the wrong thing.
|
||
|
|
|
||
|
|
## When to Use
|
||
|
|
|
||
|
|
**Required for:**
|
||
|
|
- New tool concepts (skills, agents, commands)
|
||
|
|
- Significant architectural changes
|
||
|
|
- User has nascent idea not ready for implementation
|
||
|
|
- Multiple valid approaches exist
|
||
|
|
|
||
|
|
**Skip when:**
|
||
|
|
- User gives clear, unambiguous instructions
|
||
|
|
- Task is purely mechanical (file moves, renames)
|
||
|
|
- Fixing specific bugs with obvious solutions
|
||
|
|
- User explicitly says "just do it"
|
||
|
|
|
||
|
|
## Core Principles
|
||
|
|
|
||
|
|
1. **Draft first, ask later.** Don't interrogate the user. Use judgment to draft, then surface gaps.
|
||
|
|
|
||
|
|
2. **Conceptual, not implementation.** Output is design decisions and constraints. Implementation details come later.
|
||
|
|
|
||
|
|
3. **Always checkpoint.** Write a defer file after critique. Nothing is lost if user leaves.
|
||
|
|
|
||
|
|
4. **Self-critique before presenting.** Find your own issues before the user does.
|
||
|
|
|
||
|
|
## Implementation Checklist
|
||
|
|
|
||
|
|
Tools implementing this pattern must:
|
||
|
|
|
||
|
|
- [ ] Detect when brainstorming is needed (vs execution)
|
||
|
|
- [ ] Draft a complete conceptual design first
|
||
|
|
- [ ] Self-critique against domain anti-patterns
|
||
|
|
- [ ] Surface trade-offs requiring user decisions
|
||
|
|
- [ ] Write checkpoint to `.claude/deferred/`
|
||
|
|
- [ ] Give user clear options: leave or continue
|
||
|
|
|
||
|
|
## Workflow Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
1. Understand intent (1-2 questions max)
|
||
|
|
└─→ What problem? Who consumes it? Constraints?
|
||
|
|
|
||
|
|
2. Draft conceptual design
|
||
|
|
└─→ Purpose, decisions, structure, constraints
|
||
|
|
└─→ Identify script candidates (mechanical, repeatable components)
|
||
|
|
|
||
|
|
3. Self-critique
|
||
|
|
└─→ Alignment with intent
|
||
|
|
└─→ Domain anti-patterns
|
||
|
|
└─→ Missing pieces
|
||
|
|
└─→ Over-engineering
|
||
|
|
|
||
|
|
4. Present and checkpoint
|
||
|
|
└─→ Show design
|
||
|
|
└─→ Write defer file
|
||
|
|
└─→ Offer: leave or continue
|
||
|
|
|
||
|
|
5. Resolution (if continuing)
|
||
|
|
└─→ Work through trade-offs
|
||
|
|
└─→ Dispatch subagents for implementation
|
||
|
|
```
|
||
|
|
|
||
|
|
## Output Format
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
## Purpose
|
||
|
|
What this solves, in one paragraph.
|
||
|
|
|
||
|
|
## Design Decisions
|
||
|
|
- Decision 1: choice and why
|
||
|
|
- Decision 2: ...
|
||
|
|
|
||
|
|
## Structure
|
||
|
|
Conceptual architecture - components, relationships, boundaries.
|
||
|
|
|
||
|
|
## Constraints
|
||
|
|
- What this must do
|
||
|
|
- What this must NOT do
|
||
|
|
|
||
|
|
## Open Questions
|
||
|
|
- Questions that surfaced during drafting
|
||
|
|
```
|
||
|
|
|
||
|
|
## Anti-patterns
|
||
|
|
|
||
|
|
**Question barrage:** Asking 5+ questions before drafting anything. Draft with assumptions, then validate.
|
||
|
|
|
||
|
|
**Implementation creep:** Including file paths, code snippets, exact structures. Stay conceptual.
|
||
|
|
|
||
|
|
**Skipping critique:** Presenting first draft without self-review. Always critique before showing.
|
||
|
|
|
||
|
|
**Forced brainstorming:** Brainstorming when user gave clear instructions. Most interactions are execution, not exploration.
|
||
|
|
|
||
|
|
## Script Identification
|
||
|
|
|
||
|
|
When refining a skill design, identify which components are mechanical vs. judgment-based. Mechanical components (validation, scaffolding, structured transformations) are script candidates—note these in the design output. See [Deterministic Scripting](deterministic-scripting.md) for heuristics and language selection.
|
||
|
|
|
||
|
|
## Cross-references
|
||
|
|
|
||
|
|
- [Defer Work](../defer-work/workflow.md) - Checkpoint mechanism
|
||
|
|
- [Domain Hooks](../brainstorming/domain-hooks.md) - Domain-specific questions
|
||
|
|
- [Deterministic Scripting](deterministic-scripting.md) - When to use scripts vs AI
|