brainstorming

Brainstorming Skill

Turns vague intent into a documented, approved design spec through structured dialogue — before any codebase research or implementation planning begins.

Research shows that validated designs reduce planning rework by stopping assumption drift before it compounds.

This skill should behave like a disciplined design grilling session:

• walk the design tree until no planning-critical branch is unresolved
• ask the user only what the repo and docs cannot already answer
• when a strong default exists, include a recommended answer so the user can confirm or override it quickly

<HARD-GATE> Do NOT invoke any implementation skill, write any code, create beads, or take any implementation action until a design has been presented AND the user has approved it. This applies regardless of perceived simplicity. The design can be short — but it MUST exist and be approved. </HARD-GATE>

Anti-Pattern: "This is too simple to need a design"

Every new feature with unclear design goes through this process. A new config capability, a new function that expands behavior, a new UI path — if the shape is still fuzzy, this is where you turn it into an approved spec. "Simple" feature work is where unexamined assumptions cause the most wasted planning work. The spec can be a paragraph. But you MUST present it and get approval.

This is not the path for trivial non-feature corrections already covered by small_change or Micro Mode. If the request is only a wording fix, local correction, or similarly bounded non-feature adjustment, follow the lighter route defined by pulse:using-pulse instead of forcing a brainstorming spec.

Quick Reference

| Step | What you do | What you produce | |---|---|---| | Explore context | Read just enough project material to understand what already exists | Internal context snapshot | | Assess scope | Decide whether this is one feature or multiple independent systems | Scoped brainstorming target | | Visual decision point | Decide whether upcoming questions are easier to answer by seeing options | User consent for visual support, or text-only path | | Clarifying questions | Ask one question at a time to uncover purpose, constraints, and success criteria | Validated requirements | | Approaches | Present 2–3 viable directions with trade-offs | Chosen direction | | Design | Present the solution in sections and validate incrementally | Approved design | | Spec | Write the approved design to history/<feature>/spec.md | Stable spec for exploring | | Self-review | Run the spec reviewer subagent and fix serious issues | Planning-ready spec | | User review gate | Wait for explicit approval on the written spec | Approved handoff artifact | | Handoff | Update .pulse/STATE.md and recommend pulse:exploring as the next manual step | Clean pipeline transition |

Checklist

Create a task for each item and complete them in order:

1. Explore project context — read files, docs, recent commits relevant to the request
2. Assess scope — is this one feature or multiple independent systems? (see Decomposition)
3. Offer visual support — if upcoming questions would be easier to answer by seeing options, offer visuals in their own message
4. Ask clarifying questions — one at a time; purpose, constraints, success criteria
5. Propose 2–3 approaches — with trade-offs and your recommendation
6. Present design — in sections scaled to complexity; get user approval after each section
7. Write spec doc — save to history/<feature>/spec.md and note the path
8. Spec self-review — subagent check for placeholders, contradictions, scope, ambiguity
9. User reviews spec — ask user to confirm before proceeding
10. Handoff to exploring — recommend pulse:exploring as the next manual step to lock implementation decisions

Process Flow

digraph brainstorming {
    "Explore project context" [shape=box];
    "Multi-system?" [shape=diamond];
    "Decompose first" [shape=box];
    "Visual questions ahead?" [shape=diamond];
    "Offer visual support\n(own message only)" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write spec doc" [shape=box];
    "Spec self-review (subagent)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Recommend pulse:exploring handoff" [shape=doublecircle];

    "Explore project context" -> "Multi-system?";
    "Multi-system?" -> "Decompose first" [label="yes"];
    "Multi-system?" -> "Visual questions ahead?" [label="no"];
    "Decompose first" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer visual support\n(own message only)" [label="yes"];
    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
    "Offer visual support\n(own message only)" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "Present design sections";
    "Present design sections" -> "User approves design?";
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write spec doc" [label="yes"];
    "Write spec doc" -> "Spec self-review (subagent)";
    "Spec self-review (subagent)" -> "User reviews spec?";
    "User reviews spec?" -> "Write spec doc" [label="changes requested"];
    "User reviews spec?" -> "Recommend pulse:exploring handoff" [label="approved"];
}

The terminal state is an approved spec.md plus .pulse/STATE.md update, with a recommendation to run pulse:exploring next. Do NOT invoke planning, validating, or any execution skill by default. After brainstorming, the ONLY valid next step is pulse:exploring.

Phase 1: Explore Context

Before asking any question, understand what already exists:

• Read .pulse/project-docs.json first when present, then read the listed project docs before relying on feature history alone
• If .pulse/project-docs.json is absent, detect likely project docs (README, architecture, ADR, domain docs) and read the smallest relevant set
• Reuse existing glossary/terminology from project docs when present; do not invent new terms when established names already exist
• Before asking, eliminate questions the repo can already answer. Read docs, code, and recent repo history first, then ask only for unresolved design intent.
• Check relevant files, docs, and the last few commits related to the topic
• Identify existing patterns, components, or decisions that constrain the design
• Note what can be reused vs. what needs to be created from scratch

Build an internal picture first — it makes your clarifying questions concrete instead of generic.

Phase 2: Scope Assessment

Before asking detailed questions, assess whether the request is one feature or several:

One feature — scoped work with a clear boundary. Continue normally.

Multiple independent systems — e.g., "build a platform with auth, billing, and analytics." Flag this immediately:

"This covers [A], [B], and [C] — three independent systems. Each needs its own

brainstorming session. Let's start with [most foundational]. I'll note the others for later."

Then brainstorm the first sub-system through the full flow. Each sub-system gets its own spec → exploring → planning → execution cycle.

Step-back move — use selectively

Before detailed questioning, decide whether the request needs one brief step-back pass. This is not a new phase and not a replacement for sequential questioning. It is a short framing move to help you ask better questions.

Use it only when one of these is true:

• the request names a solution but not the problem it should solve
• multiple feature shapes could satisfy the request
• the user is jumping quickly into screens, components, or flows before the core outcome is clear
• you notice yourself optimizing a local detail before th