brainstorm

Skill: Brainstorm

Objective

Help the user think through a problem, decision, or implementation idea by running parallel web research (market patterns, best practices, pitfalls, examples) and gathering specialist agent perspectives, then synthesizing the findings into a structured options matrix with a recommendation. This skill is exploratory — it does not write code, run tests, or modify the repo.

Position in the workflow:

• /brainstorm → decide what to build (this skill)
• /squad:implement → implement what was decided
• /squad:review → review what was implemented

Inviolable Rules

1. No code implementation. This skill produces a brainstorm report. It must not edit files, run scripts, run tests, or modify any user-facing persistent state. The only file this skill ever writes is the journal .squad/runs.jsonl via record_run for telemetry — gitignored, mode 0o600, not user content. Same single-writer pattern as the squad + debug + question skills.
2. No git commit, git push, or any state-mutating git command. Read-only git is fine (git log, git status, git diff for context).
3. Cite sources. Every market claim, best practice, statistic, or "industry uses X" assertion must link to the URL it came from. Unsourced claims are not allowed.
4. Multiple options. Always present at least two alternatives with explicit pros/cons. Never single-answer. The user is brainstorming, not asking for a verdict.
5. Honest gaps. When research is incomplete or a decision needs more input, surface it explicitly under "Open questions" — do not paper over.
6. No AI attribution in any artifact produced. Consistent with the global commit-authorship rule: if the brainstorm output ever gets pasted into a commit, doc, or message, it must not carry Co-Authored-By: Claude / Anthropic / AI / Generated with [...] lines.

Inputs

The skill takes one required argument (the topic) and optional flags:

Param	Default	Description
<topic>	required	Free-form text describing the problem, decision, or idea to brainstorm
--quick / --normal / --deep	--normal	--quick (3 web queries, 1 agent), --normal (6 queries, 2-3 agents), --deep (10+ queries, 4 agents + tech-lead). Same vocabulary as /squad:implement and /squad:review.
--no-web	off	Skip web research entirely. Agents-only mode. Use when offline or when the topic is purely internal-codebase.
--focus <domain>	auto	Force a domain bias: frontend, backend, infra, data, security, business, mobile. Auto-detection scans the topic text for keywords.
--sources <N>	5	Cap on web sources cited per section. Avoids dump of every result.

Step 1: Topic Understanding

Read the user's prompt and extract:

• Problem/decision: what is being decided? Phrase it as a question.
• Constraints: tech stack, team size, scale, budget, timeline (if mentioned or inferable from git log / package.json / README).
• Existing context: scan the current repo for related code, prior decisions in CHANGELOG.md or ADRs (docs/adr/, architecture/).
• Domain(s): classify into one or more of frontend / backend / infra / data / security / business / mobile.
• What "done" looks like: what would satisfy the user — a single recommendation, multiple paths to consider, a comparison table, a risk inventory?

If the topic is ambiguous, ask one clarifying question before proceeding. Do not ask a list of questions; pick the most load-bearing one.

Step 1.5: Write in_flight telemetry row

Generate a fresh run id (Date.now().toString(36) + "-" + 6 chars from [a-z0-9]) and append the in_flight row before launching Step 2's parallel research:

record_run({
  workspace_root: <cwd>,
  record: {
    schema_version: 1,
    id: <runId>,
    status: "in_flight",
    started_at: <ISO 8601 now>,
    invocation: "brainstorm",
    mode: <"quick" | "normal" | "deep" from flag, default "normal">,
    mode_source: <"user" if a depth flag was explicit, "auto" otherwise>,
    git_ref: null,
    files_count: 0,
    agents: <pre-populated array of agents you intend to dispatch in Step 3 + tech-lead-consolidator if --deep>,
    est_tokens_method: "chars-div-3.5",
    mode_warning: null,
  },
});

Pre-populate the agents array at in_flight time with one entry per specialist you'll dispatch in Step 3 (metrics zero until Step 5.5 fills them). Pre-population keeps the row informative if the run strands.

Non-blocking try/catch per shared/_Telemetry-Contract.md: I/O errors log silently; SquadError surfaces code + message verbatim. If this write fails, set a flag to skip the Step 5.5 finalisation.

Step 2: Research Plan

Build a research plan with:

Web queries (skip if --no-web)

Construct 3-10 targeted queries (count from the depth flag: 3 for --quick, 6 for --normal, 10+ for --deep). Use the current year in queries that benefit from recency:

• {topic} best practices {year}
• {topic} {dominant_stack} examples
• {topic} alternatives comparison
• {topic} common pitfalls
• {topic} performance / security / scalability / cost
• {topic} case study {year} (for industry examples)
• {topic} open source (if implementation references would help)
• {topic} vs {known_alternative} (if a comparison is implicit)

Avoid:

• Generic queries like "{topic}" alone (returns marketing pages).
• Queries that the user can find better via their internal docs (e.g., proprietary product internals).

Agents

Pick agents based on detected domains. For --quick: pick the single most relevant. For --normal: 2-3. For --deep: 4 + tech-lead. Mapping:

Domain	Primary agent
frontend	developer (UX/perf perspective)
backend	developer + architect
infra	architect + security
data	dba + architect
security	security + architect
business	product-owner
testing	qa
code quality	reviewer

tech-lead is included only at --deep (or whenever 3+ agents participate, to consolidate).

Step 3: Parallel Research and Agent Spawn

Run web queries and agent invocations in parallel in a single message:

• One WebSearch tool call per query.
• One Agent tool call per specialist.

Per-agent prompt template:

You are participating in a brainstorm — pre-implementation thinking.

## Topic
{topic restated}

## What we know so far
{problem framing, constraints, existing context}

## Your perspective
As {agent role}, contribute:
1. The 1-3 approaches you would consider, with one-line pros/cons each.
2. Domain-specific risks the user should weigh.
3. Open questions that need answers before deciding.
4. (Optional) One concrete example from your experience or prior projects.

Format: at most 400 words. Bullet points fine. Do NOT produce a full review template.
Do NOT recommend code changes — this is exploration, not implementation.
If you do not have enough context to contribute meaningfully, say so explicitly.

Step 4: Findings Synthesis

Aggregate web findings and agent perspectives into:

Market research section

Group findings by category. Cite every claim. Example:

### What the industry does
- Stripe and Block use a "saga" pattern for cross-service refund flows — [Stripe Engineering blog](url), [Square's saga implementation](url).
- 7 of the top 10 fintech APIs (per State of API 2026) implement idempotency keys via request headers — [State of API 2026](url).

### Best practices
- Always include a `request_id` in idempotency keys to disambiguate retries — [GitHub's idempotency guide](url).

### Pitfalls / anti-patterns
- Don't use the database PK as an idempotency key — collisions across retries break replays — [Postgres weekly issue 543](url).

Options matrix

Build a table of 3-5 alternatives. Columns:

#	Approach	How it works	Pros	Cons	Risk	Best when

Each row is one viable path. "Approach" is short (3-6 words). "How it works" is one sentence. Pros/cons are bullet-style condensed.

Agent perspectives

One collapsible section per agent that participated:

<details>
<summary>architect</summary>
{their perspective bullet-pointed}
</details>

Step 5: Tech-Lead Recommendation

If --deep (or 3+ agents participated), spawn the tech-lead agent with:

You are consolidating a brainstorm. Pick one option and justify.

## Topic
{topic}

## Options matrix
{the matrix from step 4}

## Web findings summary
{condensed market research, with sources}

## Specialist perspectives
{condensed bullets from each agent}

## Your task
1. Pick ONE option from the matrix as the recommendation.
2. Explain in 3-5 sentences why this option, with the trade-offs you accepted.
3. List the top 2-3 open questions that must be answered before implementation begins.
4. Suggest the immediate next step (e.g., spike, prototype, more research, /squad:implement implement).

Format: at most 400 words. No long template. No scorecard.

For --quick and --normal, the synthesizing skill itself produces the recommendation directly (no separate tech-lead spawn).

Step 5.5: Finalise telemetry row

After Step 5 synthesis completes (or after early-stop on missing topic / no-research), write the terminal half. Use the SAME id from Step 1.5:

record_run({
  workspace_root: <cwd>,
  record: {
    schema_version: 1,
    id: <same runId from Step 1.5>,
    status: "completed",                       // or "aborted" on early stop
    started_at: <same started_at from Step 1.5>,
    completed_at: <ISO 8601 now>,
    duration_ms: <completed_at - started_at>,
    invocation: "brainstorm",
    mode: <same>,
    mode_source: <same>,
    git_ref: null,
    files_count: 0,
    agents: <same agent list, now with batch_duration_ms + prompt_chars + response_chars filled in for each Step 3 dispatch; score: null, severity_score: null>,
    verdict: null,           // brainstorm runs don't carry a verdict
    weighted_score: null,    // no rubric
    est_tokens_method: "chars-div-3.5",
    mode_warning: null,
  },
});

Same non-blocking try/catch; on SquadError write the fallback row per shared/_Telemetry-Contract.md.

Step 6: Delivery

Output in this format:

# Brainstorm: {short topic}

## Topic
{problem framing in 1-2 sentences}

## Context I gathered
- {key fact 1 from repo / git / user prompt}
- {key fact 2}

## Market research

### What the industry does
- {finding} — [source title](url)
- {finding} — [source title](url)

### Best practices
- {practice} — [source](url)

### Pitfalls / anti-patterns
- {pitfall} — [source](url)

## Options matrix

| # | Approach | How it works | Pros | Cons | Risk | Best when |
|---|----------|--------------|------|------|------|-----------|
| A | ... | ... | ... | ... | Low | small scale, low traffic |
| B | ... | ... | ... | ... | Med | growth phase |
| C | ... | ... | ... | ... | High | enterprise / regulated |

## Agent perspectives

<details><summary>architect</summary>{view}</details>
<details><summary>developer</summary>{view}</details>

## Recommendation
**Option {letter}** — {one-paragraph justification including the trade-offs accepted}.

## Open questions
- {gap 1 — needs decision or more research}
- {gap 2}
- {gap 3}

## Next steps
- `/squad:implement implement {selected option}` to execute
- `/brainstorm --focus {domain} {sub-topic}` to deep-dive on a specific concern
- Spike / prototype: {1-2 line description if appropriate}
- Continue research on: {gap}

Sources used:
- [Title 1](url)
- [Title 2](url)
- ...

If --no-web was passed, omit "Market research" section and replace with a one-line note: Web research disabled — agents-only brainstorm.

If the user passed --quick, output is condensed: skip "Agent perspectives" details, drop the matrix to 2-3 options, and replace the recommendation paragraph with one sentence.

Edge Cases

• Topic is too vague ("help me think about scaling") → ask one clarifying question first; do not run research blindly.
• Topic is purely internal (only repo-specific, no public reference) → suggest --no-web and note that web research is unlikely to add value.
• Topic touches a regulated domain (PCI, HIPAA, GDPR, SOX) → flag the regulatory angle in the Open questions section even if the user did not mention it. Do not produce legal/compliance advice — point at the right specialists/docs.
• Web search returns thin results → state honestly: "Web research surfaced limited material; the recommendation leans on agent perspectives and codebase context." Do not invent citations.
• Agent reports "not enough context" → record it and proceed; do not retry with more context just to force an opinion.
• The user wants implementation, not brainstorm → redirect: "This sounds like a /squad:implement task. /brainstorm is for pre-implementation exploration."

Boundaries

• This skill never edits files.
• This skill never runs state-mutating git commands.
• This skill never claims authority for legal/regulatory/compliance verdicts — it points at sources and specialists.
• This skill never invents URLs or sources. If unsure, omit the citation and note the gap.
• This skill produces text only.

Considerations

Cost vs depth

Query / agent counts per mode are in the Inputs table. Token ballpark: --quick ~5-10K, --normal ~20-40K, --deep ~60-100K. Same --quick / --normal / --deep vocabulary as the other squad skills.

When to use vs alternatives

• Use /brainstorm when: deciding what to build, comparing approaches, scanning industry, exploring a problem space.
• Use /squad:implement when: you've decided and want to implement.
• Use /squad:review when: implementation is done and you want a multi-perspective review.
• Use WebSearch directly when: you need one specific answer, not a brainstorm framing.

Sources reliability

Prefer (in this order): official docs, recognized engineering blogs (e.g., Stripe, AWS, Cloudflare, Google Cloud, Microsoft, Netflix Tech Blog), academic / standards bodies, recognized newsletters (Pragmatic Engineer, Increment), GitHub READMEs of widely-adopted libraries, conference talks. Avoid: SEO listicles, vendor-marketing pieces masquerading as articles, AI-generated content farms.

Output format consistency

Always close with a "Next steps" block and a flat list of all sources used. The Next steps block is the bridge from brainstorm to action — never omit it.