Brainstorm — Design Phase

Brainstorm — Design Phase

Turn ideas into fully-formed specs through structured dialogue: explore context, assess scope, ask one question at a time, propose approaches, present the design section by section, and hand off to /flow:plan.

<HARD-GATE> Do NOT invoke `/flow:plan`, write any code, scaffold any files, or take any implementation action until the spec has been written, self-reviewed, and the user has explicitly approved it. </HARD-GATE>

---

Process Flow

Start
  |
  v
[1. Explore project context]
  Read CLAUDE.md, project files, recent git log.
  Note any output path or naming conventions CLAUDE.md specifies.
  |
  v
[2. Assess scope]
  Does the request describe multiple independent subsystems?
  |
  YES --> Flag decomposition immediately. Do not ask detailed questions yet.
  |       Help the user decompose into sub-projects, then brainstorm the first one.
  |
  NO
  |
  v
[3. Ask clarifying questions]
  One question per message. Multiple choice preferred.
  Focus: purpose, constraints, success criteria.
  |
  v
[4. Auto-detect visual questions]
  Is this question about layout, mockups, diagrams, or visual comparison?
  |
  YES --> Offer visual companion (first time only, its own message).
  |       If accepted: start server, track PID, serve mockup.
  |       Subsequent visual questions in the same session reuse the server.
  |
  NO --> Stay in terminal even if companion is active.
  |
  v
[5. Propose 2-3 approaches]
  Lead with recommendation. Explain trade-offs.
  |
  v
[6. Present design section by section]
  Scale each section to its complexity.
  Ask "Does this section look right?" after each one.
  Revise before moving forward.
  |
  v
[7. Write spec]
  Save to docs/specs/<YYYY-MM-DD>-<topic>.md
  (or the path CLAUDE.md specifies — that path always wins).
  |
  v
[8. Self-review]
  Run the four checks inline. Fix issues before showing the user.
  |
  v
[9. User reviews spec]
  Ask the user to review the file. Wait for explicit approval.
  If changes requested: update the file, re-run self-review, re-ask.
  |
  v
[10. Hand off to /flow:plan]

---

Step-by-Step Rules

Step 1: Explore Project Context

Before asking anything, read:

• CLAUDE.md — project conventions, output paths, naming rules, toolchain
• Key project files (package.json / pyproject.toml / Cargo.toml, src/ structure)
• Recent git log: git log --oneline -10

Record any path CLAUDE.md specifies for specs. That path takes precedence over the default docs/specs/ in every subsequent step.

Step 2: Assess Scope

Scope check happens BEFORE detailed questions. If the request names multiple independent subsystems (e.g., "build a platform with chat, billing, file storage, and analytics"), stop immediately:

"This touches several independent systems. Before we refine details, let's map the pieces:

• System A: [description]
• System B: [description]
• System C: [description]

Each should get its own brainstorm → plan → execute cycle. Which do you want to start with?"

Do not ask detailed clarifying questions about a project that needs decomposition first.

Step 3: Clarifying Questions

• One question per message, always.
• Multiple choice preferred: give 2-4 options with a clear default.
• Open-ended is fine when options would artificially constrain the answer.
• Focus on: purpose, users, constraints, success criteria.
• Stop asking once you have enough to propose approaches. Three to five questions is usually sufficient.

Step 4: Visual Companion (Conditional)

Offer the visual companion ONLY when the question at hand is inherently visual: mockups, wireframes, layout comparisons, architecture diagrams. Do not offer it for requirement questions, tradeoff lists, or conceptual choices — those are terminal questions regardless of topic.

First visual question of the session — send this as its own message, nothing else:

"This question would be clearer if I can show it to you in a browser. I can render mockups and diagrams as we go. Want me to fire up the visual companion? (Requires opening a local URL)"

Wait for the response. If declined, continue in terminal for all visual questions — diagrams can be rendered as ASCII.

If accepted: locate the plugin directory first, then run the start script:

# Note: Script paths are relative to the fakoli-flow plugin directory.
# Use Glob to locate it if needed:
#   ${CLAUDE_PLUGIN_ROOT}/skills/brainstorm/scripts/

Run ${CLAUDE_PLUGIN_ROOT}/skills/brainstorm/scripts/start-server.sh. The script writes a PID file to $STATE_DIR. Before each subsequent write to the server, run ${CLAUDE_PLUGIN_ROOT}/skills/brainstorm/scripts/check-server.sh "$STATE_DIR". If it returns "dead", run start-server.sh again — no need to ask the user again. They already consented.

After starting or re-verifying the server, print exactly one line:

[visual: active on http://localhost:52121]

or if offline and will restart on next visual question:

[visual: offline — will restart on next visual question]

Textual questions always stay in terminal — even after the companion is active.

Step 5: Propose 2-3 Approaches

Present options conversationally. Structure each option as:

• Name
• One-sentence description
• Key trade-offs

Lead with your recommendation and explain why in one sentence. Do not present options as equal if they are not.

Step 6: Present Design Section by Section

Once you understand what you are building, present the design. Do not present everything at once.

Sections to cover (scale each to its complexity — a sentence if simple, a short paragraph if nuanced):

1. Architecture — the overall structure and components
2. Data model / interfaces — types, schemas, or key APIs
3. Data flow — how information moves through the system
4. Error handling — failure modes and how they surface
5. Testing — how correctness will be verified

After each section: "Does this section look right before we move on?"

Be ready to revise. A design that gets approved section by section is more reliable than one presented all at once.

Step 7: Write the Spec

Save the validated design to:

• The path specified in CLAUDE.md (if present) — this always takes priority
• Otherwise: docs/specs/<YYYY-MM-DD>-<topic>.md

The spec should be complete enough that a plan can be written from it without re-asking you. Include: goal, context, architectural decisions, data model, key behaviors, error handling, acceptance criteria, and out-of-scope items.

Step 8: Self-Review

After writing, check the spec against these four criteria. Fix issues inline — no need to re-read:

1. Placeholder scan — Any "TBD", "TODO", "implement later", or vague requirements? Resolve them.
2. Internal consistency — Does any section contradict another? Does the architecture match the feature descriptions?
3. Scope — Is this focused enough for a single plan, or does it need further decomposition?
4. Ambiguity — Could any requirement be interpreted two ways? Pick one and make it explicit.

Step 9: User Review Gate

After self-review passes:

"Spec written to <path>. Please review it and let me know if you want any changes before we start planning."

Wait. If changes are requested: update the file, re-run self-review, ask again.

Only proceed to step 10 once the user explicitly approves.

Step 10: Hand Off

Invoke /flow:plan and pass the spec file path.

---

When NOT to Brainstorm

Use /flow:quick instead when:

• The task is a bug fix in 1-2 files
• Adding or renaming a parameter
• Fixing a typo, import, or config value
• Any task where brainstorming would take longer than the fix itself

Rule of thumb: if you can describe the complete change in one sentence and it touches fewer than 3 files, use /flow:quick.

Use brainstorm for: new features, architectural changes, anything spanning multiple files, anything where the user would benefit from seeing a spec before any code is written.

---

Key Differences from SuperPowers Brainstorming

SuperPowers brainstorming	fakoli-flow brainstorm
Offers visual companion every session, as its own message	Offers only when the current question is inherently visual
Saves spec to docs/superpowers/specs/ always	Reads CLAUDE.md first; honors any path it specifies
Loads ~22k tokens of skill content at startup	~500 tokens (metadata only) — lazy by design
Loses track of server state across sessions	PID file + liveness check + auto-restart on next visual question
Questions are terminal-only	Works headless — questions through any active channel (Discord, Telegram, etc.)
Scope check happens during question phase	Scope check happens BEFORE detailed questions

---

Key Principles

• One question at a time. Never two questions in the same message.
• Multiple choice preferred. Easier to answer than open-ended when options are known.
• Scope before details. Decompose large projects before refining any piece.
• Visual only when visual. Do not default to the companion. Offer it when visual understanding is genuinely better than text.
• CLAUDE.md wins on paths. The project's declared conventions override built-in defaults.
• No implementation until approved. The hard gate is absolute.
• Works headless. All questions are text-first. The visual companion is additive, never required.