brainstorm

name	brainstorm
description	Turn a fuzzy idea into a concrete, reviewable spec via structured dialogue. THINK stage entry. Triggers: "brainstorm", "design", "spec this out", "let's think through".
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob","WebSearch"]
when_to_use	Use at the start of any new feature, project, or design decision. Produces a spec document that is the single input to writing-plans. NOT for product-market validation — use office-hours for that (its design-doc output is for product discovery, not sprint pipeline).
argument-hint	[idea]
produces	docs/superomni/specs/spec-[branch]-[session]-[date].md
consumes	[]

Preamble (Core)

Status protocol — end every session with one of: DONE (evidence provided) · DONE_WITH_CONCERNS (list each) · BLOCKED (state what blocks you) · NEEDS_CONTEXT (state what you need).

Auto-advance — pipeline: THINK → PLAN → REVIEW → BUILD → VERIFY → RELEASE. Only human gate is spec approval at THINK. On DONE at other stages, print [STAGE] DONE -> advancing to [NEXT-STAGE] and invoke the next skill. On any non-DONE status at any stage, STOP.

Output directory — all artifacts go in docs/superomni/<kind>/<kind>-[branch]-[session]-[date].md. See CLAUDE.md for the full directory map.

TACIT-DENSE — before high-tacit decisions, classify D1 (domain expertise) · D2 (user-facing UX) · D3 (team culture) · D4 (novel pattern). On hit, output TACIT-DENSE [D#]: [question] — My default: [recommendation]. See reference for actions.

Anti-sycophancy — take a position on every significant question. Name flaws directly. No filler ("that's interesting", "you might consider", "that could work").

Telemetry (local only) — at session end, log bin/analytics-log. Nothing leaves the machine.

See preamble-ref.md for detailed protocols.

Brainstorming & Specification

Goal: Transform a fuzzy idea into a concrete, reviewable spec document.

Iron Law: Search Before Building

For doc-alignment & declaration-precedence discipline (declaration precedence, quantitative-claim pinning, forbidden-token-as-drifted-expression), see the Convention section in docs/SKILL-DATA-FLOW.md.

Before designing anything:

1. Layer 1 — Tried and true: Does a well-established solution already exist?
2. Layer 2 — New and popular: Is there a recently popular approach? Evaluate carefully.
3. Layer 3 — First principles: Only design from scratch if nothing fits.

Run: grep -r "similar functionality" . --include="*.md" -l to check existing docs.

Phase 1: Problem Crystallization

Ask ONE clarifying question at a time. Do not ask multiple questions at once.

Required understanding before proceeding:

• What is the problem being solved? (not the solution)
• Who experiences this problem?
• What does success look like? (measurable outcome)
• What constraints exist? (time, technology, team size)
• What already exists that's related?
• TACIT probe: at least 3 of 5 dimensions answered

TACIT Five-Dimensional Probe

After initial understanding is established, systematically probe these 5 tacit knowledge dimensions. Each dimension requires exactly ONE targeted question:

T - Team & Culture -> "Does your team have any preferences or taboos regarding [key technical choice in this task]?" Purpose: Capture implicit team conventions and consensus

A - Aesthetic & Style -> "Is there existing code or a system you consider 'feels right' as a reference?" Purpose: Capture code style, architecture taste, implicit quality standards Note: If docs/superomni/style-profiles/ exists, reference it instead of asking

C - Constraints Unstated -> "What absolutely must NOT be touched or changed this time?" Purpose: Capture hidden boundaries, forbidden zones, political constraints

I - Integration Expectations -> "After this feature is complete, what will the user do first?" Purpose: Capture implicit acceptance scenarios and success experience

T - Time & Quality Trade-offs -> "If you had to cut one feature to ship on time, which would you cut first?" Purpose: Capture implicit priority weights and non-negotiables

TACIT Probe Gate: Before proceeding to Phase 2, verify:

• At least 3 of 5 TACIT dimensions received an explicit answer
• If any answer revealed new constraints, problem definition has been updated
• FAIL -> continue clarification, do NOT enter Phase 2

Rule: Ask one question. Wait for answer. Then ask the next. Confirmation rule: each answer (text input or single-choice) is an immediate confirmation — do NOT re-ask or add a "confirm?" prompt after the user replies.

Phase 2: Solution Space Exploration

Mandatory Alternatives Rule: The 3 options MUST collectively include both:

• One "Minimal Viable" approach — fewest files, smallest diff, ships fastest
• One "Ideal Architecture" approach — best long-term trajectory, most elegant

These two can be any 2 of the 3 options (A, B, or C); the third slot is flexible. Each option must include: Name, 1-sentence summary, Effort (S/M/L), Pros (2), Cons (2), Reuses (existing code leveraged).

RECOMMENDATION: State which option you recommend and the one-line reason. The user chooses.

Generate 3 candidate approaches, then always offer an "Other" option for the user's own idea:

Option A: [name] — [1-sentence description]
  Pros: [pro 1], [pro 2]
  Cons: [con 1], [con 2]
  Effort: [S/M/L]
  Reuses: [existing code or infra leveraged]

Option B: [name] — [1-sentence description]
  Pros: [pro 1], [pro 2]
  Cons: [con 1], [con 2]
  Effort: [S/M/L]
  Reuses: [existing code or infra leveraged]

Option C: [name] — [1-sentence description]
  Pros: [pro 1], [pro 2]
  Cons: [con 1], [con 2]
  Effort: [S/M/L]
  Reuses: [existing code or infra leveraged]

Option D (Other): describe your own approach — ___________

Apply the 6 Decision Principles when evaluating:

• Prefer completeness (covers more cases)
• Prefer DRY (reuses existing)
• Prefer explicit over clever

Surface only TASTE decisions to the user. Decide MECHANICAL ones silently.

Phase 3: Visual Companion (if applicable)

For UI or architecture work, produce a text diagram or ASCII wireframe. See visual-companion.md for diagram formats.

Frontend Design Integration: If the spec involves UI components, pages, or visual design:

• Note in the spec: "This involves UI work — recommend running the frontend-design skill during BUILD to ensure design quality."
• When generating acceptance criteria, include: "Passes frontend-designer agent review at 7+/10 on all dimensions"

Phase 4: Spec Document Output

mkdir -p docs/superomni/specs
_BRANCH=$(git branch --show-current 2>/dev/null | tr '/' '-' || echo "unknown")
_SESSION="<auto-generate-kebab-case-from-context>"  # e.g., auth-refactor, vibe-skill
_DATE=$(date +%Y%m%d)
_SPEC_FILE="docs/superomni/specs/spec-${_BRANCH}-${_SESSION}-${_DATE}.md"

Produce docs/superomni/specs/spec-[branch]-[session]-[date].md with this structure:

# [Feature Name] — Spec

## Problem
[1 paragraph: what is broken or missing and for whom]

## Goals
- [Measurable outcome 1]
- [Measurable outcome 2]

## Non-Goals (YAGNI)
- [What we are explicitly NOT building]

## Proposed Solution
[Selected approach + rationale]

## Key Design Decisions
| Decision | Choice | Rationale | Principle Applied |

## Acceptance Criteria
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]

## Open Questions
- [Any unresolved taste decisions requiring user input]

Phase 5: Spec Self-Review (Inline)

Before presenting to user, run this inline check (no sub-agent needed):

Placeholder scan — any TBD, TODO, [placeholder], "similar to X", undefined references? → If yes: fill them in before proceeding

Scope check — does Proposed Solution match Goals exactly? → Over-scoped: move extras to Non-Goals → Under-scoped: add missing requirements to Goals

Internal consistency — do Acceptance Criteria actually test the Proposed Solution? → Any criterion that can't be traced to the solution → revise or remove

Ambiguity check — is each Acceptance Criterion yes/no testable? → Vague criteria ("works correctly", "performs well") → make measurable

If all 4 checks pass → proceed to Phase 6. If any fail → fix in spec and re-check.

Phase 6: Human Gate — Spec Approval

THINK is the human gate. After the spec is generated and self-reviewed, STOP and present the spec to the user for approval.

Present:

SPEC READY FOR REVIEW
════════════════════════════════════════
File: [spec file path]

[Summary: 3-5 bullet points of the proposed solution]

Acceptance criteria:
  - [criterion 1]
  - [criterion 2]
  ...

Please review the spec above.
  Y) Approve — proceed to PLAN (all subsequent stages will auto-execute)
  N) Reject — describe what needs to change
  [Or provide revision notes directly]
════════════════════════════════════════

Wait for user response. This is the ONLY human gate in the entire pipeline. The user's reply IS the approval signal — no marker file or filesystem flag is written.

• If approved (e.g., user replies "继续" / "approve" / "A") → report DONE and auto-advance to PLAN (writing-plans). All subsequent stages (PLAN → REVIEW → BUILD → VERIFY → RELEASE) execute automatically without further user input.
• If rejected → revise the spec based on feedback and re-present for review.

Report status: DONE — spec written, reviewed, and approved by user. Path: [spec file path]