Brainstorming Ideas Into Designs

Turn ideas into fully formed designs through collaborative dialogue. Understand context, ask questions one at a time, present design, get approval, write spec.

<HARD-GATE> Do NOT write code, scaffold a project, or take implementation action until you have produced a design. Interactive sessions: get explicit user approval before implementation. Autonomous/non-interactive sessions: self-review the design, record assumptions, and proceed only if no open questions remain. </HARD-GATE>

Anti-Pattern: "Too Simple for Design"

Every design decision goes through this process. If the task involves choosing between approaches, defining behavior, or creating new functionality — brainstorm it, even if it seems simple. "Simple" projects are where unexamined assumptions cause the most waste.

Exempt from brainstorming: Tasks requiring zero design decisions — renaming, fixing typos, adding comments, deleting files, updating config values. These are trivial edits (< 3 steps, single file) and proceed directly after gate checks.

Scope-Based Effort

Scale the process to the task size:

Task Size	Design Depth	Questions	Spec
Small (single component, < 5 files)	Component + approach summary	3-5 questions	Short spec, save to specs directory (per CONVENTIONS.md)
Medium (multi-component, 5-15 files)	Full architecture sections	5-8 questions, one at a time	Full spec with components, testing, error handling
Large (15+ files or cross-system)	Decompose into sub-projects first	Scope decomposition before detail questions	One spec per sub-project

Note: Trivial tasks (< 3 steps, single file, no design decisions) are exempt from brainstorming entirely — they proceed directly after gate checks.

Checklist

You MUST complete these in order. Work through each step.

1. Explore project context — Read PROJECT.md and MAP.md. Identify the 3-5 files most relevant to the proposed change from MAP.md. Read those files. Do not read more than 5 files before proceeding to step 2 — if you still lack context, ask the user instead of reading more.
2. Assess scope — if multiple independent subsystems, decompose first (don't refine details of something that needs splitting)
3. Ask clarifying questions — one topic per message, prefer multiple choice, understand purpose/constraints/success criteria
4. Propose 2-3 approaches — with trade-offs, lead with your recommendation and concrete reasons why
5. Present design in sections — scaled to complexity, get user approval after each section
6. Write design doc — save to project's specs directory (default: docs/specs/YYYY-MM-DD-<topic>-design.md; agree path with user if directory doesn't exist)
7. Spec self-review — check for placeholders, contradictions, ambiguity, scope gaps (fix inline)
8. User reviews written spec — ask user to review the file before proceeding. Autonomous default: If user is unavailable, proceed after self-review passes with no issues found.
9. Transition — for trivial tasks, go directly to execution; otherwise invoke mbscode:writing-plans

How to Ask Questions

HARD-GATE (interactive sessions): One question per message. You may bundle 2-3 closely related sub-questions (related = same component AND same design decision; e.g., "username format: email or custom? min length?") but NEVER ask about different topics in one message. If you catch yourself writing two unrelated questions, STOP and send only the first one.

Autonomous sessions: Compile all questions, answer them yourself using the Autonomous Decision Hierarchy (existing code patterns > CONVENTIONS.md > language idioms > community choice), and record your assumptions in the spec. If a question genuinely can't be answered from context, stop and report the blocker.

Prefer multiple choice:

Which auth approach should we use?

1. JWT tokens (Recommended — stateless, scales horizontally)
2. Session-based (simpler, but requires server-side state)
3. OAuth only (if this is purely a third-party auth wrapper)

Lead with your recommendation. Don't present neutral options — you have expertise. State which option you'd choose and WHY with a concrete reason. Then present alternatives.

When to ask open-ended: Only when the answer genuinely can't be predicted (e.g., "What's the primary use case?").

Stop asking when: You have enough to propose approaches. Ask until you can confidently define: inputs, outputs, error handling, and test strategy. Typically 3-5 questions.

How to Propose Approaches

Present 2-3 approaches. For EACH:

• What: One sentence describing the approach
• Why it works: Concrete technical advantage
• Trade-off: What you give up
• Your verdict: Why you'd pick this one or not

### Approach A: Modular Plugin Architecture (Recommended)
Each skill is an independent markdown file with YAML frontmatter.
**Why:** Zero coupling, any AI can read it, community can contribute independently.
**Trade-off:** No runtime validation — skill quality depends on writing discipline.

### Approach B: Typed Skill Schema
Skills are YAML/JSON with a strict schema validated at load time.
**Why:** Catches malformed skills before they reach the AI.
**Trade-off:** Higher barrier to contribution, schema maintenance overhead.

**My recommendation:** Approach A. The validation cost isn't worth it because
skills are read by AI, not executed. A bad skill wastes tokens; it doesn't crash.

How to Present the Design

Scale sections to their complexity. A few sentences if single-component. Up to 300 words if multi-component with trade-offs.

Ask after each section: "Does this look right so far?"

Cover these areas (skip if genuinely not applicable):

• Architecture — components and how they connect
• Data flow — what goes in, what comes out, how it moves
• Interfaces — how components talk to each other
• Error handling — what can go wrong, how to recover
• Testing strategy — what to test, how to verify

Design for isolation:

• Each unit has one clear purpose
• Clear interfaces between units
• Can be understood without reading internals
• Can be changed without breaking consumers
• Small enough to hold in context

Working in Existing Codebases

• Explore the current structure before proposing changes. Follow existing patterns.
• Where existing code has problems that affect the work (e.g., file too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design.
• Don't propose unrelated refactoring. Stay focused on what serves the current goal.

Spec Document Format

# <Feature Name> — Design Spec

## Goal
One sentence. What does this build?

## Architecture
How the system works. Components, data flow, key interactions.

## Components

### Component A: <Name>
**Purpose:** What it does
**Interface:** How other components use it
**Implementation notes:** Key decisions, constraints

### Component B: <Name>
...

## Error Handling
What can fail and how each failure is handled.

## Acceptance Criteria
Feature-level success conditions. These are NOT task-level — they describe end-to-end outcomes:
- Given [context], when [action], then [outcome].

## Testing Strategy
What to test and how. Which components need unit tests,
which need integration tests, what the acceptance criteria are.

## Open Questions
(Remove this section when all questions are resolved)

## Decisions Made
- [Decision]: [Chosen approach] because [reason]. Alternative: [rejected option] because [reason].

Spec Self-Review

After writing the spec, review it yourself:

1. Placeholder scan: Any "TBD", "TODO", vague requirements, incomplete sections? Fix them.
2. Internal consistency: Do sections contradict each other? Does architecture match features?
3. Scope check: Is this one implementation plan or does it need splitting?
4. Ambiguity check: Could any requirement be read two ways? Pick one, make it explicit.
5. Decision scan: Every design decision from the discussion is captured in the Decisions Made section. If a decision was deferred, it's marked "DEFERRED: [reason]" — not silently omitted.
6. Acceptance criteria check: Do criteria cover the entire feature flow end-to-end, not just individual components?

Fix issues inline. Then ask user to review the written file.

After Approval

Non-trivial tasks (spec was written):

1. Commit the spec to git
2. Say: "Spec written to docs/specs/<filename>. Please review and let me know if you want changes."
3. Wait for user approval
4. Invoke mbscode:writing-plans. Do NOT invoke any implementation skill.

Trivial tasks (no formal spec written):

Proceed directly to implementation without invoking a skill — you have enough context from the design discussion. mbscode:verification-before-completion still applies before claiming done. If you created a feature branch, invoke mbscode:finishing-a-development-branch when done.

Transitions

Triggered by: Intent to build something new (features, components, systems). Not keyword-based — evaluate user intent, not specific words. Also invoked by: mbscode:systematic-debugging when a bug reveals a design issue After completion: mbscode:writing-plans (non-trivial) or direct implementation + mbscode:finishing-a-development-branch (trivial, on feature branch)

Red Flags

Thought	Reality
"I know what they want"	You don't. Ask.
"One approach is obviously right"	Present alternatives anyway — your human might see something you don't
"Let me just start coding"	Design first. Always.
"This design is too detailed"	Detailed design = fewer surprises during implementation
"They said 'just build it'"	"Build" is WHAT. Brainstorming determines HOW.