brainstorming

Brainstorming

Turn ideas into designs through dialogue: understand context, ask one question at a time, propose alternatives, get explicit approval. The hard gate: no implementation skill, no code, no scaffolding until the user has approved a presented design. Every project, no matter how simple.

Why "too simple to design" is wrong

Simple projects are where unexamined assumptions waste the most work, because nobody bothers to check them. A todo list, a one-function utility, a config change: all go through the gate. The design can be three sentences. It cannot be skipped.

Workflow

Work these steps in order. Create a task for each.

1. Explore project context. Files, docs, recent commits. In existing codebases, learn the current patterns before proposing anything.
2. Check scope. If the request spans multiple independent subsystems ("a platform with chat, billing, and analytics"), stop refining details. Decompose into sub-projects, order them, then brainstorm the first one. Each sub-project gets its own design, plan, and implementation cycle.
3. Ask clarifying questions, one per message. Focus on purpose, constraints, and success criteria. Prefer multiple choice when the options are enumerable; open-ended otherwise. A topic that needs depth gets multiple messages, not one compound question.
4. Propose 2-3 approaches with trade-offs. Lead with your recommendation and the reason for it.
5. Present the design in sections. Scale each section to its complexity: a few sentences when straightforward, a few paragraphs when nuanced. Cover architecture, components, data flow, error handling, testing. Ask after each section whether it looks right. Revise until approved.
6. Write the design doc. Save to docs/specs/YYYY-MM-DD-<topic>-design.md (user preference overrides the path) and commit it.
7. Self-review the spec. Placeholder scan (no TBD, no vague requirements), internal consistency, scope check (one implementation plan's worth?), ambiguity check (any requirement readable two ways gets pinned to one). Fix inline, no re-review loop.
8. User reviews the written spec. Ask them to read the file and approve or request changes. Wait. Changes trigger a rewrite and another self-review.
9. Hand off to writing-plans. That is the only next step. Do not invoke any implementation skill from here.

Design for clarity

Break the system into units with one clear purpose each, communicating through defined interfaces. For every unit you should be able to answer: what does it do, how is it used, what does it depend on. If internals cannot change without breaking consumers, the boundaries are wrong. Apply YAGNI ruthlessly: strip features the goal does not need. In existing code, include targeted improvements the work touches, and nothing else.

Good vs bad

Bad: User says "add CSV export". You reply with four stacked questions about delimiters, encodings, auth, and scheduling, then start coding while they answer. The gate is blown and the questions were noise.

Good: User says "add CSV export". You check how existing exports work, ask one question ("Export the current filtered view, or the full dataset? I'd recommend the filtered view because it matches what the user sees"), converge in a few exchanges, present a five-sentence design, get a yes, write the spec, get it approved, then invoke writing-plans.

Verification

Before invoking writing-plans, check the trail. Expect: a committed design doc exists at the spec path, the user gave an explicit approval message for both the presented design and the written spec, and zero code or scaffolding changes exist in the working tree. If any expectation fails, go back to the step that produced it. Uncommitted spec: commit it. No approval message: ask for one. Code already written: stop, disclose it, and get the design approved before keeping or deleting it.

Completion checklist

• [ ] Project context explored before questioning
• [ ] Questions asked one at a time
• [ ] 2-3 approaches proposed with a recommendation
• [ ] Design presented in sections and approved
• [ ] Spec written, self-reviewed, committed
• [ ] User approved the written spec file
• [ ] No implementation started
• [ ] Next step is writing-plans and nothing else

Any box unchecked: not done. Fix or say so.

Red flags

Verbatim excuses that signal the gate is about to be blown:

• "This is too simple to need a design"
• "I'll just prototype while we talk"
• "The user obviously wants X, no need to ask"
• "I'll write the code first and document the design after"
• "Approval is implied, they didn't object"

All of these mean the same thing: skipping the gate. Closure rule: if there is no explicit user approval message for a presented design, implementation has not been authorized, and any code written is unauthorized regardless of how confident you feel.

Footguns

• Compound questions. Three questions in one message get one vague answer. Fix: one question per message, always.
• Designing past the scope. Refining button labels for a project that needs decomposition first. Fix: run the scope check before detail questions.
• Silent spec drift. The presented design and the written spec disagree because ideas evolved mid-writing. Fix: the self-review step compares the spec against what was approved; differences go back to the user.