brainstorming

Brainstorming

Turn an idea into an approved spec before any code is written.

Hard gate

Do NOT write code, scaffold files, or invoke any implementation skill until you have presented a design AND the user has explicitly approved it. This applies even to "simple" projects. A todo list, a one-line script, a config tweak — all of them. The design can be short, but it must exist and be approved.

Process

1. Explore project context — read relevant files, recent commits, any docs. Understand what already exists.
2. Ask clarifying questions, one at a time. Multiple choice is easier to answer than open-ended. Focus on purpose, constraints, and success criteria.
3. Propose 2–3 approaches with trade-offs and your recommendation.
4. Present the design in sections scaled to complexity. Cover architecture, components, data flow, error handling, testing. Ask for yes/no after each section.
5. Write the spec to docs/supertools/specs/YYYY-MM-DD-<topic>.md after the user approves.
6. Self-review the spec for placeholders, contradictions, scope creep, and ambiguity. Fix inline.
7. Commit the spec to git so the design is durable and reviewable independently of the conversation.
8. Ask the user to review the written spec before transitioning.
9. Hand off to writing-plans to produce the implementation plan.

Decomposition check

Before refining details, check scope. If the request describes multiple independent subsystems ("build a platform with chat, billing, and analytics"), say so immediately and propose splitting into separate specs — one per subsystem. Each spec should produce something working on its own.

Working in existing codebases

Follow existing patterns. Where existing code has problems that affect the work (a file too big, tangled responsibilities), include targeted fixes — but stay focused on the goal. No unrelated refactoring.

Principles

• One question at a time. Don't overwhelm.
• YAGNI. Strip features that aren't needed now.
• Small, focused units. Each piece does one thing and is testable in isolation.
• Be flexible. Go back and clarify when something doesn't make sense.

Terminal state

After the user approves the written spec, the ONLY skill you invoke next is writing-plans. Do not jump to implementation skills directly.