| name | spec-brainstorm |
| description | Discover WHAT for a selected feature/problem before PRD or planning when behavior, scope, users, success criteria, or handoff context remain unresolved. Do not use for open-ended ideation, brownfield PRD authoring/refinement/validation, clear HOW planning/task compilation, implementation/debug/review/setup, generated runtime mirror fixes, factual answers, or cleanup. |
| argument-hint | [feature/problem] |
Brainstorm a Feature or Improvement
Purpose
Clarify WHAT before requirements/planning; planning defines HOW. Create docs/brainstorms/ only for durable handoff.
Workflow Contract Summary
When To Use
Use when the user has a selected or user-framed problem, feature, or improvement and behavior/scope/users/success/planning handoff context remain unresolved; planning would otherwise invent WHAT to build.
When Not To Use
Do not use for open-ended idea generation, brownfield PRD authoring/refinement/validation, clear implementation planning, execution/debug/review/setup, single-document cleanup/summarization, or narrow factual answers.
Inputs
Feature/problem, context, optional brainstorm doc, one-question decisions.
Outputs
Requirements doc or brief alignment summary.
Artifacts
docs/brainstorms/; generated runtime mirrors are not source.
Failure Modes
Missing feature, unresolved choice, universal flow, or wrong workflow.
Workflow
Assess, ask, synthesize, capture, hand off.
Downstream Consumers
spec-plan, owners, reviewers, work/review flows.
Near-Neighbor Exit Cues
Stop before Phase 1 when another route fits: idea_generation->ideation; brownfield_prd->PRD; clear_plan_request->plan; doc_review/code_review->review; debug_request->debug; execution_ready->work; direct_cleanup->direct.
Route-Out Shape
Wrong-entry cases return a compact chat-consumable shape for the user or parent entry router, not a schema-validated artifact:
status: not_applicable | handoff | degraded
reason_code: idea_generation | brownfield_prd | clear_plan_request | execution_ready | debug_request | doc_review | direct_cleanup | missing_feature_description | insufficient_evidence
recommended_next_action: <current-host entrypoint or direct action>
limitation: <why brainstorm should not continue>
source_refs: <repo-relative paths when source evidence was read>
Examples As Context
evals/routing-cases.json records positive WHAT-discovery triggers and near-neighbor route-out examples. It is not a deterministic router or semantic proof.
Scenario Capability
Follows docs/contracts/workflows/scenario-capability-matrix.md (default).
Overrides: none
Capability-Class Evidence Boundary
Follows docs/contracts/project-graph-consumption.md: capability-class candidates (code-graph, project-graph) are advisory. Check readiness_status; the WHAT must come from user dialogue and source confirmation, never the candidate. Record provider_untrusted, never-block, separate lifecycle.fallback_used, and fall back to direct source reads.
Reference Routing
Refs: references/interaction-rules.md; references/context-and-evidence.md; references/discovery-flow.md; references/approach-exploration.md; references/synthesis-summary.md; references/brainstorm-sections.md, references/requirements-capture.md, and references/markdown-rendering.md for Phase 3 canonical markdown requirements capture. HTML is an optional sidecar only; do not replace markdown without focused downstream consumer tests. Phase 4: references/handoff.md; governance: references/evaluation-governance.md.
Feature Description
<feature_description> #$ARGUMENTS </feature_description>
If empty, ask for the feature/problem/improvement; stop until answered.
Execution Flow
Flow: 0 references/discovery-flow.md; 1 interaction/context/discovery; 2 references/approach-exploration.md; 2.5 Phase 2.5: Synthesis Summary: Read references/synthesis-summary.md; 3 Phase 3 refs; 4 references/handoff.md.
