sunrain520/spec-first/spec-brainstorm

Brainstorm a Feature or Improvement

Note: Use the current date from the active host context. Use this when weighting external sources and dating artifacts.

Brainstorming helps answer WHAT to build through collaborative dialogue. It precedes spec-plan, which enriches the same unified plan artifact with HOW to build it.

The durable output of this workflow is a requirements-only unified plan. In other workflows this might be called a lightweight PRD or feature brief. In spec-first, keep the workflow name brainstorm, but write the first version of the plan artifact under docs/plans/ with artifact_readiness: requirements-only so 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. It also never delivers an adopt/switch/replace verdict on a named external candidate — that is spec-pov's job (see the 0.1c gate); routing it out by name is mandatory even when no project context is visible.

Workflow Contract Summary

• 输入： 尚未收敛的产品想法、问题、目标用户、约束，以及可回源的仓库或外部证据。
• 输出： artifact_readiness: requirements-only 的统一计划，明确 Product Contract、范围边界、成功标准、未决问题与证据限制。
• 硬出口： 关键产品决定未确认、目标仓库或文档 owner 不明确、证据不足以支撑声明，或请求已属于规划、实现、调试、审查时停止并交还 owning route。
• 权威： 用户确认产品语义；LLM 负责探索与语义综合；脚本和 provider 只准备 advisory facts。该 workflow 不授权实现、commit 或 landing。
• 消费者： spec-plan、spec-doc-review、产品 owner 与后续需求/规划审查者。

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. Keep implementation out of the Product Contract by default - Do not include libraries, schemas, endpoints, file layouts, or code-level design unless the brainstorm itself is inherently about a technical or architectural change.
5. Right-size the artifact - Simple work gets a compact requirements-only unified plan or brief alignment. Larger work gets a fuller Product Contract. Do not add ceremony that does not help planning.
6. 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.
7. Keep product confirmation singular - The current conversation user is the only human product confirmer. Ask one highest-impact independent product question at a time; specialist material is evidence, not a second confirmation route.

Interaction Rules

These rules apply to every brainstorm, including the universal (non-software) flow routed to references/universal-brainstorming.md.

1. Ask one question at a time - One question per turn, even when sub-questions feel related. Stacking several questions in a single message produces diluted answers; pick the single most useful one and ask it.
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. Default to the platform's blocking question tool - Use AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex. These tools include a free-text fallback, so well-chosen options scaffold the answer without confining it. This default holds for opening and elicitation questions too, not only narrowing. Fall back to numbered options in chat only when no blocking tool exists in the harness (including ToolSearch returning no match for it) or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.
5. Use an open-ended question only when the question is genuinely open - Drop the blocking tool when the answer is inherently narrative, when presented options would steer a diagnostic or introspective answer, or when you cannot write 3-4 genuinely distinct, plausibly-correct options without padding. The test: if you'd be straining to fill the option slots, the question is open — ask it open-ended. Rule 1 still applies: one question per turn.
6. Open-ended questions earn their place only when they're specific enough to elicit a substantive answer - Apply Rule 5 silently: just ask the question, never narrate the form choice. The question must give the user something concrete to anchor on. Good: "What's the most concrete thing someone's already done about this — paid for it, built a workaround, quit a tool over it?" — it names what counts as an answer. Too thin: "What's your take?" — nothing to bite into, and framings that imply a short answer ("briefly", yes/no) waste the open question the same way.

Output Guidance

• Prioritize decision-relevant detail - Preserve the facts, tradeoffs, and caveats needed for the next decision; trim introductions, repetition, and optional background first.

Dispatch Authorization Boundary

在派发 grounding scout、claim verifier、Slack researcher 或 repo profiler 前，记录两个彼此独立的 run-local 事实：

worker_dispatch_authorization: authorized | missing
capability_probe: not_applicable | attempted | unavailable
worker_dispatch_capability: available | missing | unknown
worker_context_isolation: isolated | inherited | unknown
worker_model_override: supported | unsupported | unknown
worker_bounded_parallelism: supported | unsupported | unknown

workflow invocation does not authorize dispatch。只有当前用户或可见 upstream handoff 明确请求 subagent、delegated work、persona 或 parallel work 时，worker_dispatch_authorization 才是 authorized；工具存在、权限设置、brainstorm tier、用户请求搜索某个来源或本 Skill 被调用，都不构成派发授权。缺授权时不得探测 tool schema，固定为 capability_probe: not_applicable + worker_dispatch_capability: unknown，inline 或 serial 执行并记录 dispatch_authorization_missing。只有授权后才把 current-session registry/schema 作为 provider_untrusted evidence 检查：确认缺失时记录 subagent_capability_missing；surface 不可用、schema 不完整或候选不唯一时记录 worker_capability_unproven，均 inline 或 serial。隔离、模型覆盖和有界并发只取 live facts；required isolation 未满足时保持依赖 gate 打开，model unknown 时继承，parallelism unknown 时串行。记录 worker_dispatch_outcome。Inline fallback 可以保留同一 evidence budget，但不得声称 fresh-context、independent scout 或 multi-agent coverage。

Model Tiers

Worker model selection is tiered by task shape, never hardcoded to a host or model name. When dispatching the Phase 1.1 grounding scout, the Phase 2.6 claim verifier, or the opt-in Slack researcher, read references/model-tiers.md for the tier definitions (extraction / generation / ceiling) and the degradation rule when worker_model_override or dispatch capability is unavailable.

Feature Description

<feature_description> #<invocation arguments supplied by the current host> </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

Before asking scope questions, read references/settled-decisions.md. Classify conversation-carried choices as settled, directives, or unlabeled proposals. Carry settled product decisions forward without re-asking them; spend at most one in-pipeline challenge on an unexamined directive. The Product Contract's Key Decision entry is the single owner of each accepted product decision: annotate it there and reference it elsewhere instead of repeating the decision in Requirements, Scope Boundaries, synthesis, or handoff prose.

0.0 Resolve Output Mode

Determine OUTPUT_FORMAT before any other phase fires. Output mode is exclusive — the requirements-only unified plan is written as either markdown (.md) OR HTML (.html), never both. Precedence: in-prompt request > user-stated preference > config > default (md), with a hard pipeline-mode override.

Read config. The repo root is pre-resolved at skill load: !git rev-parse --show-toplevel

If the line above is an absolute path, use it as <repo-root>. If it is empty, shows an error, or still shows a backtick command string (a harness that did not run the pre-resolution), resolve <repo-root> at runtime by running git rev-parse --show-toplevel with the shell tool. Then read <repo-root>/.spec-first/config.local.yaml with the native file-read tool. If the root cannot be resolved (not a git repo) or the file does not exist, fall through to the defaults below.

Resolution steps:

1. In-prompt request. Reason over the user's prompt for this run for a request about this document's output format, expressed either as the output: shorthand or in plain language ("make this a webpage", "I want this in HTML"). On an explicit format, match it case-insensitively to md/html, and ignore the output: shorthand token when reading the rest of the prompt as the feature description. Distinguish a request about the document's format from a format named as subject matter: "explore an HTML export feature" is the work, not a doc-format request — do not switch on it.

• output: alone (no value) → no-op, fall through to step 2.
• output:<unknown> (e.g., output:pdf) → drop the token, fall through to step 2, and remember to emit a one-line note above the post-generation menu after final resolution: Ignored unknown output: value '<value>' — using <resolved_format> instead. where <resolved_format> is the value OUTPUT_FORMAT actually resolved to after the remaining precedence steps. Do not hardcode md in the note — that misleads users when config has set HTML.

1. User-stated preference. If this prompt holds no format request, honor an output-format preference (markdown vs HTML) the user established earlier — earlier in this session, in your memory, or written into their active instructions — that is already in your context (match md/html case-insensitively). A remembered preference is more current than the rarely-edited config, so it overrides the config in step 3. Do not open or search instruction files to find it — act only on a preference already present in your context; if none is, fall through to the config.
2. Config. If steps 1-2 did not resolve and the config file read above has an active (non-commented) brainstorm_output: key whose value matches md or html (case-insensitive), use it. Missing, invalid, or commented values fall through silently. Critical: lines starting with # are YAML comments and must be ignored — the shipped config template includes commented examples like # brainstorm_output: html to document the option, and matching those as active settings would silently force HTML mode on every run without the user having opted in.
3. Default. Otherwise OUTPUT_FORMAT=md.
4. Pipeline override. When invoked from LFG or any disable-model-invocation context, force OUTPUT_FORMAT=md regardless of steps 1-4. Downstream consumers (spec-plan, spec-work) parse markdown reliably; HTML in pipeline runs is unnecessary friction.

Token-parsing convention: only literal-prefix flag tokens (output:, mode:, delegate: where applicable) are consumed and stripped. Other <word>:<word> tokens — including conventional commit prefixes like feat:, fix:, chore: that may appear inside a feature description — pass through verbatim.