brainstorm

Brainstorm a Feature or Improvement

Use the actual current date from runtime context when dating requirements documents.

Brainstorming helps answer WHAT to build through collaborative dialogue. It precedes $fw:plan, which answers HOW to build it.

The durable output of this workflow is a requirements document or, when the user asks for one, a lightweight spec packet. Treat PRD as a user synonym for a product-flavored spec, but use spec as Flywheel's canonical artifact term. Keep the workflow name brainstorm, and make the written artifact strong enough that planning does not need to invent product behavior, scope boundaries, or success criteria.

This skill does not implement code. It explores, clarifies, and documents decisions for later planning or execution.

IMPORTANT: All file references in generated documents must use repo-relative paths such as src/models/user.rb, never absolute paths. Absolute paths break portability across machines, worktrees, and teammates.

Do not preload every reference file. Load only the one needed for the current phase so the working context stays tight.

Reference Loading Map

• Read references/universal-brainstorming.md only when Phase 0 routes the task into non-software brainstorming.
• Read references/requirements-capture.md when Phase 3 begins and a durable requirements document should be created or updated.
• Read references/spec-packet.md when the user asks for a spec, PRD, product requirements, issue-ready requirements, or a synthesis of the current conversation into a planning-ready artifact.
• Read references/spec-grilling.md for every software brainstorm that may produce a durable requirements doc or spec packet. Skip it only for alignment-only trivial work where no artifact will be produced.
• Read references/brainstorm-examples.md when taking the clear-requirements fast path, preparing the synthesis checkpoint, structuring approach comparisons, drafting the requirements document, or repairing output that is drifting from the expected shape.
• Read ../references/research/activation-heuristics.md when deciding whether to reuse a saved research brief or run a focused research pass before deeper brainstorming.
• Read ../references/research/source-ranking-and-synthesis.md when current published guidance or unfamiliar territory would materially change the requirements, scope, or approach comparison.
• Read ../references/architecture-code-quality/activation-heuristics.md when the brainstorm is explicitly about technical boundaries, architecture, or named pattern choices that may materially affect scope or behavior.
• Read ../references/architecture-code-quality/pattern-families.md only when a technical brainstorm needs help comparing candidate patterns or architectural styles at a requirements level.
• Read references/visual-communication.md when deciding whether a diagram, table, or other visual aid would make the requirements or approach comparison easier to understand.
• Read references/handoff.md when Phase 4 begins and the brainstorm is ready to hand off, pause, or continue.

Core Principles

1. Assess scope first - Match the amount of ceremony to the size and ambiguity of the work.
2. Be a thinking partner - Suggest alternatives, challenge assumptions, and explore what-ifs instead of only extracting requirements.
3. Resolve product decisions here - User-facing behavior, scope boundaries, and success criteria belong in this workflow. Detailed implementation belongs in planning.
4. Use spec as the canonical term - When the user says PRD, treat it as a product-flavored spec request unless their organization has a stricter convention.
5. Keep implementation out of the requirements doc by default - Do not include libraries, schemas, endpoints, file layouts, or code-level design unless the brainstorm itself is inherently about a technical, architectural, or pattern-selection change.
6. Right-size the artifact - Simple work gets a compact requirements document or brief alignment. Larger work gets a fuller document. Do not add ceremony that does not help planning.
7. Apply YAGNI to carrying cost, not coding effort - Prefer the simplest approach that delivers meaningful value. Avoid speculative complexity and hypothetical future-proofing, but low-cost polish or delight is worth including when its ongoing cost is small and easy to maintain.
8. Treat user answers as durable inputs - preferences, constraints, corrections, and examples surfaced in the dialogue should shape the requirements doc and may later become spin-worthy project guidance.
9. Use research to sharpen the brainstorm, not replace it - when current published guidance materially changes the requirements, reuse a fresh matching brief first and otherwise run only the smallest focused research pass needed before returning to requirements shaping. Fold the findings and resulting recommendation back into the requirements and approach comparison instead of emitting a side report.
10. Grill specs by default - before a material brainstorm can hand off to planning, challenge terminology, assumptions, scenarios, code/docs contradictions, and decision-record needs. The user should not have to ask for this rigor separately.

Interaction Rules

Follow ../references/host-interaction-contract.md.

1. Ask one question at a time - Do not batch several unrelated questions into one message.
2. Prefer single-select multiple choice - Use single-select when choosing one direction, one priority, or one next step.
3. Use multi-select rarely and intentionally - Use it only for compatible sets such as goals, constraints, non-goals, or success criteria that can all coexist. If prioritization matters, follow up by asking which selected item is primary.
4. Call the exact host question tool when available - When asking the user a question, call the host question tool named in the host interaction contract. Do not ask for raw numeric replies or render a markdown menu first when the host already offers that surface.
5. Use host task tracking for multi-step passes - When the brainstorm spans multiple material steps, create and maintain a short task list with the host task-tracking tool named in the host interaction contract.
6. Keep explicit options narrow - When presenting answer choices, keep them to 2-3 portable options by default. Use a fourth only when the active host question surface supports it.
7. Lead with the recommendation, keep a freeform path available - when presenting options, put the recommended choice first and rely on the host's native freeform final path when it exists.
8. Prefer targeted dialogue over silent inference - ask at least one material question when the answer would sharpen the problem, scope, priorities, or success criteria.

Output Guidance

• Keep outputs concise - Prefer short sections, brief bullets, and only enough detail to support the next decision.
• Use repo-relative paths - When referencing files, use paths relative to the repo root such as src/models/user.rb, never absolute paths.

Feature Description

<feature_description> #$ARGUMENTS </feature_description>

If the feature description above is empty, ask the user: "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."

Do not proceed until you have a feature description from the user.

Execution Flow

Phase 0: Resume, Assess, and Route

0.1 Resume Existing Work When Appropriate

If the user references an existing brainstorm topic or document, or there is an obvious recent matching *-requirements.md file in docs/brainstorms/:

• Read the document.
• Confirm with the user before resuming: "Found an existing requirements doc for [topic]. Should I continue from this, or start fresh?"
• If resuming, summarize the current state briefly, continue from its existing decisions and outstanding questions, and update the existing document instead of creating a duplicate.

0.1b Classify Task Domain

Before proceeding to Phase 0.2, classify whether this is a software task. The key question is: does the task involve building, modifying, or architecting software? -- not whether the task mentions software topics.

Software (continue to Phase 0.2) -- the task references code, repositories, APIs, databases, or asks to build, modify, debug, or deploy software.

Non-software brainstorming (route to universal brainstorming) -- BOTH conditions must be true:

• None of the software signals above are present.
• The task describes something the user wants to explore, decide, or think through in a non-software domain.

Neither (respond directly, skip all brainstorming phases) -- the input is a quick-help request, error message, factual question, or single-step task that does not need a brainstorm.

If non-software brainstorming is detected: Read references/universal-brainstorming.md and use those facilitation principles to brainstorm with the user naturally. Do not follow the software brainstorming phases below.

0.2 Assess Whether Brainstorming Is Needed

Clear requirements indicators:

• Specific acceptance criteria provided.
• Referenced existing patterns to follow.
• Described exact expected behavior.
• Constrained, well-defined scope.

If requirements are already clear:

Keep the interaction brief. Confirm understanding and present concise next-step options rather than forcing a long brainstorm. Only write a short requirements document when a durable handoff to planning or later review would be valuable. Skip Phase 1.1 and 1.2 entirely and choose exactly one fast path:

• Alignment only -- use when no material product decision remains and no durable artifact is needed. Give a compact synthesis and proceed to Phase 4.
• Confirm then capture -- use when only 1-2 product decisions still need confirmation before writing. Ask those questions in Phase 1.3, then go to Phase 3.
• Capture now -- use when requirements are already clear and a durable requirements document would be valuable. Go straight to Phase 3.

Even on this fast path, verify any checkable claim about existing repo infrastructure before writing it into a requirements document. If not verified, label it as an unverified assumption.

0.3 Assess Scope

Use the feature description plus a light repo scan to classify the work:

• Lightweight - small, well-bounded, low ambiguity
• Standard - normal feature or bounded refactor with some decisions to make
• Deep - cross-cutting, strategic, or highly ambiguous

If the scope is unclear, ask one targeted question to disambiguate and then proceed.

Phase 1: Understand the Idea

1.1 Existing Context Scan

Scan the repo before substantive brainstorming. Match depth to scope:

Lightweight -- Search for the topic, check if something similar already exists, and move on.

Standard and Deep -- Two passes:

Constraint Check -- Check project instruction files (AGENTS.md, and CLAUDE.md only if retained as compatibility context) for workflow, product, or scope constraints that affect the brainstorm. If these add nothing, move on.

Topic Scan -- Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc, or active- repo docs/solutions/ entry). When the active repo has docs/solutions/, search that local store by frontmatter using files_touched, module, tags, problem_type, component, and title before opening full docs. Prefer doc_status: active and follow superseded_by when present. Skim adjacent examples covering similar behavior. When the active repo has docs/research/ and the topic is current-practice-sensitive, unfamiliar, or explicitly research-driven, search that local store by frontmatter and title before broad external research. Match on topic, keywords, reuse_targets, and title. Prefer a matching fresh brief whose reuse_targets include brainstorm. If it is stale or partial, reuse it as context and note the need for targeted follow-up research instead of trusting it blindly.

Context and decision scan -- For software brainstorms that may produce a durable artifact, look for existing project language and prior decisions before the first substantive question. Check CONTEXT-MAP.md, CONTEXT.md, docs/context/, docs/decisions/, docs/adr/, and area-local context or ADR docs when they exist. Use those artifacts to challenge terminology and decision assumptions during the brainstorm.

If nothing obvious appears after a short scan, say so and continue. Two rules govern technical depth during the scan:

1. Verify before claiming -- When the brainstorm touches checkable infrastructure (database tables, routes, config files, dependencies, model definitions), read the relevant source files to confirm what actually exists. Any claim that something is absent -- a missing table, an endpoint that does not exist, a dependency not in the manifest, a config option with no current support -- must be verified against the codebase first; if not verified, label it as an unverified assumption. This applies to every brainstorm regardless of topic.
2. Defer design decisions to planning -- Implementation details like schemas, migration strategies, endpoint structure, or deployment topology belong in planning, not here -- unless the brainstorm is itself about a technical or architectural decision, in which case those details are the subject of the brainstorm and should be explored.
3. Architecture-bearing brainstorms stay high level -- when boundaries, bounded contexts, named patterns, or distributed posture affect scope or behavior, capture the decision surface and recommended direction, but leave file-level implementation and execution sequencing for planning.

Research context (conditional, proactive) -- may auto-run when evidence quality would otherwise be weak. Route by condition:

• Matching fresh brief: Reuse it and say briefly that the brainstorm is being grounded with saved research.
• No matching brief + current-practice-sensitive or unfamiliar topic: Say plainly that a short research pass is being done on the user's behalf, gather only the smallest current source set likely to change requirements, then continue the brainstorm.
• Explicit no external research or local-only constraint: Stay local, say that choice is intentional, and label any freshness limits.
• After research: Fold the findings into questions, approach comparisons, and requirement capture. Carry forward the recommendation the evidence supports. Do not replace the brainstorm artifact with a standalone research report.

Slack context (opt-in, Standard and Deep only) -- never auto-dispatch. Route by condition:

• Tools available + user asked: Dispatch the available Slack research skill or tool with a brief summary of the brainstorm topic alongside Phase 1.1 work. Incorporate findings into constraint and context awareness.
• Tools available + user did not ask: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
• No tools + user asked: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."

1.2 Product Pressure Test

Before generating approaches, challenge the request to catch misframing. Match depth to scope:

Lightweight:

• Is this solving the real user problem?
• Are we duplicating something that already covers this?
• Is there a clearly better framing with near-zero extra cost?

Standard:

• Is this the right problem, or a proxy for a more important one?
• What user or business outcome actually matters here?
• What happens if we do nothing?
• Is there a nearby framing that creates more user value without more carrying cost? If so, what complexity does it add?
• Given the current project state, user goal, and constraints, what is the single highest-leverage move right now: the request as framed, a reframing, one adjacent addition, a simplification, or doing nothing?
• Favor moves that compound value, reduce future carrying cost, or make the product meaningfully more useful or compelling.
• Use the result to sharpen the conversation, not to bulldoze the user's intent.

Deep -- Standard questions plus:

• What durable capability should this create in 6-12 months?
• Does this move the product toward that, or is it only a local patch?

1.2b Spec Grill Checkpoint

For every software brainstorm that may produce a durable requirements doc or spec packet, read references/spec-grilling.md and apply it before the synthesis checkpoint. This is automatic when fw:shape routes into fw:brainstorm.

Keep the grill proportional:

• Lightweight work gets a brief terminology, scope, and success-criteria challenge.
• Standard and Deep work also get scenario pressure, repo-truth checks, and decision/context checks.

Ask one material question at a time with a recommended answer when repo truth cannot resolve the issue. If the missing answer would not change the spec, document the assumption and continue.

1.3 Collaborative Dialogue

Follow the Interaction Rules above. Call the exact host question tool named in the host interaction contract when that tool is available.

Guidelines:

• Ask what the user is already thinking before offering your own ideas. This surfaces hidden context and prevents fixation on AI-generated framings.
• Start broad (problem, users, value) then narrow (constraints, exclusions, edge cases).
• Clarify the problem frame, validate assumptions, and ask about success criteria.
• When the likely answer space is predictable, ask with 2-3 portable options instead of a fully open prompt.
• Reflect back what changed after each answer so the user can see what is now understood and what is still open.
• Make requirements concrete enough that planning will not need to invent behavior.
• Surface dependencies or prerequisites only when they materially affect scope.
• Resolve product decisions here; leave technical implementation choices for planning.
• Bring ideas, alternatives, and challenges instead of only interviewing.

Exit condition: Continue until the idea is clear OR the user explicitly wants to proceed.

1.3b Synthesis Checkpoint

Before moving to Phase 2 or Phase 3, summarize the current understanding in a compact checkpoint. Cover:

• problem frame
• target user or stakeholder
• what changed from the user's starting frame
• in-scope behavior
• out-of-scope boundary or non-goal
• success criteria
• unresolved product decisions, if any
• likely next stage or next decision

If any of those cannot be stated concretely, ask one more targeted question before proceeding.

If the checkpoint or later structured output starts drifting, read references/brainstorm-examples.md before continuing.

Phase 2: Explore Approaches

If multiple plausible directions remain, propose 2-3 concrete approaches based on research and conversation. Otherwise state the recommended direction directly.

Use at least one non-obvious angle -- inversion (what if we did the opposite?), constraint removal (what if X were not a limitation?), or analogy from how another domain solves this. The first approaches that come to mind are usually variations on the same axis.

Present approaches first, then evaluate. Let the user see all options before hearing which one is recommended -- leading with a recommendation before the user has seen alternatives anchors the conversation prematurely.

When useful, include one deliberately higher-upside alternative:

• Identify what adjacent addition or reframing would most increase usefulness, future-speed value, or durability without disproportionate carrying cost. Present it as a challenger option alongside the baseline, not as the default. Omit it when the work is already obviously over-scoped or the baseline request is clearly the right move.

For each approach, provide:

• Approach: [short name]
• Shape: [2-3 sentence description]
• Optimizes for: [primary benefit]
• Main risk: [largest downside or uncertainty]
• Best when: [situation where this is the right fit]

Keep the format and order consistent across all approaches. Do not exceed 3 approaches. If the user needs to choose between them, keep the choice set to 2-3 portable options by default.

After presenting all approaches, state your recommendation and explain why. Prefer simpler solutions when added complexity creates real carrying cost, but do not reject low-cost, high-value polish just because it is not strictly necessary.

If one approach is clearly best and alternatives are not meaningful, skip the menu and state the recommendation directly.

If relevant, call out whether the choice is:

• Reuse an existing pattern
• Extend an existing capability
• Build something net new

Phase 3: Capture the Requirements

Write or update a requirements document only when the conversation produced durable decisions worth preserving. Read references/requirements-capture.md for the document template, formatting rules, and completeness checks. If a visual aid may materially improve comprehension, also read references/visual-communication.md.

When research materially shaped the requirements, capture only the decision-changing conclusions, the recommended direction they support, or cite the saved brief. Do not turn the requirements document into a source dump.

Before finalizing a requirements doc or spec packet, reapply the grill checkpoint: project terms are consistent, fuzzy language has a canonical term, important scenarios have been stress-tested, repo/code contradictions are surfaced, and any context or ADR-worthy decision has been routed to decision or recorded as an explicit open decision.

For Lightweight brainstorms, keep the document compact. Skip document creation when the user only needs brief alignment and no durable decisions need to be preserved.

Phase 3.5: Document Review

When a requirements document was created or updated, run document-review in mode:headless on it before presenting handoff options. Pass the document path. If the skill is somehow unavailable in the current environment, manually review the document for clarity, scope, simplification opportunities, portability, and completeness.

If document-review auto-applied fixes, note them briefly when presenting handoff options. If it surfaces residual P0 or P1 findings, or a clearly blocking top-ranked item, mention that so the user can decide whether to address it before proceeding.

The handoff must offer a document-review option before planning. If the review surfaces issues that could change product behavior, scope, success criteria, or the definition of done, route back into questions or brainstorming before planning unless the user explicitly accepts the risk as an assumption.

When document-review surfaces architectural or scope-shaping complexity that looks heavier than the stated goal requires, call that out explicitly before offering handoff options so the user can choose whether to keep or simplify the documented shape.

When document-review surfaces runtime observability or validation blind spots, call that out explicitly before offering handoff options so the user can decide whether to sharpen the support story before planning.

When document review is complete, proceed to Phase 4.

Phase 4: Handoff

Present next-step options and execute the user's selection. Read references/handoff.md for the option logic, dispatch instructions, and closing summary format.