4.3 KiB
| name | description |
|---|---|
| brainstorming | Explore intent, requirements, and design BEFORE any creative or build work - new features, components, functionality, behavior changes, refactors, or new tools and scripts. Produces a reviewed spec instead of jumping straight to code. Use when a request is vague, open-ended, or bigger than a one-line change, and any time the user says: let us build X, can you add X, I want a tool that, how should we design this, brainstorm, spec this out, what are the options. Run before writing-plans. |
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
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 and get user approval.
HARD GATE: Do NOT write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity — a todo list, a single-function utility, a config change all go through this.
Checklist
- Explore project context — check files, docs, recent commits
- Ask clarifying questions — one at a time, understand purpose/constraints/success criteria. Prefer multiple choice when possible.
- Propose 2-3 approaches — with trade-offs, lead with your recommendation and reasoning
- Present design — in sections scaled to complexity (a few sentences if straightforward, up to 200-300 words if nuanced). Ask after each section whether it looks right. Cover: architecture, components, data flow, error handling, testing.
- Write design doc — save to
docs/plans/YYYY-MM-DD-<topic>-design.mdand commit if in a git repo (skip if user prefers otherwise or no repo) - Spec self-review — check for placeholders (TBD/TODO), internal contradictions, scope creep, ambiguity. Fix inline.
- User reviews written spec — ask user to review the spec file before proceeding
- Transition to implementation — invoke the writing-plans skill to create an implementation plan. Do NOT invoke any other implementation skill directly.
Key Principles
- One question at a time — don't overwhelm
- Multiple choice preferred over open-ended when possible
- YAGNI ruthlessly — remove unnecessary features from all designs
- Always propose 2-3 alternatives before settling
- Incremental validation — present design, get approval before moving on
- Be flexible — go back and clarify when something doesn't make sense
Design for isolation and clarity
Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood/tested independently. For each unit: what does it do, how do you use it, what does it depend on? Can someone understand it without reading internals? Can you change internals without breaking consumers?
Working in existing codebases
Explore current structure before proposing changes. Follow existing patterns. Where existing code has problems affecting the work (a file grown too large, unclear boundaries), include targeted improvements as part of the design. Don't propose unrelated refactoring.
Scope check
If the request describes multiple independent subsystems (e.g. "build a platform with chat, billing, and analytics"), flag this immediately and help decompose into sub-projects before brainstorming any one of them in detail. Each sub-project gets its own spec → plan → implementation cycle.
Spec Self-Review (after writing the doc)
- Placeholder scan: any "TBD"/"TODO"/incomplete sections? Fix them.
- Internal consistency: do sections contradict each other?
- Scope check: focused enough for a single implementation plan?
- Ambiguity check: could any requirement be read two ways? Pick one, make it explicit.
User Review Gate
After the spec review loop passes:
"Spec written and committed to
<path>. Please review it and let me know if you want to make any changes before we start writing out the implementation plan." Wait for response. If changes requested, make them and re-run the review loop. Only proceed once approved.
Terminal state
The only next step after brainstorming is invoking the writing-plans skill. Do not jump to any other implementation skill.