Brainstorm

brainstorm

Overview

| Field | Contract | | --- | --- | | Purpose | Turn unclear intent into a chosen direction that can be planned. | | Primary input | Vague request, brainstorm request, competing ideas, or an early feature/problem brief. | | Primary output | Confirmed direction, accepted tradeoffs, hidden assumptions, and optionally plans/YYMMDD-{slug}/brainstorm.md. | | Boundary | Do not produce an implementation plan or start coding; hand off to plan when planning is needed. | | Next handoff | plan [--tdd] plans/YYMMDD-{slug}/brainstorm.md or end session. |

Resources

| Need | Read | | --- | --- | | Step 1-6 technique detail (interview format, scope fields, research routing, direction rubric, debate rules) | references/decision-flow.md |

Load the reference when running the full flow (default or --hard). In --fast, the compressed step contracts below are enough.

Modes

Default (no flag): scale depth to uncertainty — the full decision flow, with each step's ceremony proportional to how unclear the intent still is.

| Mode | Behavior | | --- | --- | | --fast | Small idea or quick direction check. Still run scout --repo, then compress: hypothesis plus at most 2-3 discovery questions, 2 directions in analysis, one-pass debate, consensus. Durable brainstorm.md only when the user asks or a plan handoff is confirmed. | | --hard | Full pipeline, every step mandatory: scout, discovery with unknown-knowns probe, scope, bounded web research (or explicit skip reason), 2-3 direction analysis, brutal-honesty debate, explicit consensus confirmation, durable brainstorm.md. Offer blindspot first when the area is unfamiliar. |

In every mode, scout --repo and evidence-grounded claims are non-negotiable; modes change ceremony, not the rules. If HTML is requested for the report, hand the written brainstorm.md to preview --html.

Support Skill Triggers

Load support skills only when the brainstorm actually needs that lens:

| Trigger | Load | | --- | --- | | Repo context, local patterns, unknown modules | scout --repo | | User says they do not understand the area | scout --repo, then the blindspot skill only for local unknown unknowns | | External/current behavior, alternatives, or best-practice tradeoffs | scout --research (owns source-grounding vs researcher routing) | | HTML preview, visual hierarchy, comparison tables, mockups | preview --html | | User confirms implementation planning | plan | | Explicit @advisor mention, or --hard with high-stakes directions | advisor agent for Steps 4-5 |

Operating Principles

Use this as one connected decision flow, not a checklist of independent exercises. Each step produces state that the next step must use:

scout(repo) -> discovery(intent review) -> scope -> research(web) -> analysis
-> debate(brutal honesty) -> consensus -> report -> handoff

When invoked explicitly (/brainstorm), run the full artifact workflow. When triggered opportunistically, scale the depth of each step to the user's request, but do not skip the initial repo scout: even lightweight brainstorming should know whether the repo already contains relevant patterns or constraints.

Users who brainstorm don't know the technical landscape — that's why they're here. Avoid asking the user for repo/module details that tools can discover. Keep questions focused on intent, audience, success, and scope.

Step 0 - Scout

Run scout --repo first. This is the repo scan, not web research.

Scout must return the local state the rest of the flow will use:

• project type and stack signals
• relevant modules, existing similar behavior, and prior art
• local constraints from docs, config, tests, plans, or conventions
• technical unknowns that planning must resolve

If the user says they do not understand the area, run scout --repo first and add the blindspot skill only to surface local unknown unknowns — its report and corrected assumptions feed Discovery directly. Do not turn scout into design or implementation advice.

Output: repo context and local unknowns. Discovery uses this to avoid asking technical questions the repo already answered.

Steps 1-6 - Decision Flow

Read references/decision-flow.md for the technique of each step (interview format, scope fields, research routing, direction rubric, debate rules). The contracts:

| Step | Contract | Output | | --- | --- | --- | | 1 Discovery | Hypothesis + confidence first; interview one question at a time with a guess attached; run the unknown-knowns probe; end with a line-by-line restate the user confirms. Never ask technical questions the repo answers. | Confirmed intent incl. implicit standards | | 2 Scope | Minimum useful version, Not Doing, success boundary, risk boundary, open scope questions. Propose a split when the request spans 3+ independent problems. | Scope brief | | 3 Research | External/web only, via scout --research (it owns source-grounding vs researcher routing). Keep repo and web evidence separate; record an explicit skip reason when no external claim affects the scope. | Source notes and external tradeoffs | | 4 Analysis | 2-3 directions judged against the same evidence: Pros/Cons, YAGNI/KISS/DRY, hardest part, first working version, hidden assumptions (Must/Should/Might be true). | Assessed directions | | 5 Debate | Brutal honesty: attack the weakest assumption, name failure modes and scope creep, recommend one option. Do not make every option sound equally good. | Surviving options + recommendation | | 6 Consensus | User chooses/refines/confirms; record direction, rationale, accepted tradeoffs, open assumptions, what will not be pursued. | Chosen direction |

Advisor routing: when the user mentions @advisor in the brainstorm request, or mode is --hard and the directions carry high-stakes tradeoffs, run Steps 4-5 through the advisor agent — hand it the scope brief, research notes, and candidate directions as a compact bundle; its Advisor Report supplies the assessed directions and recommendation that Consensus puts to the user. Never spawn it by default: brainstorm is the cheap diverge stage.

Step 7 - Report

When a durable handoff is useful, create or reuse one work-item folder and write the report as Markdown. Only produce another format when the user explicitly asked for one (--html or a named format) — do not pause the flow to ask about formats.

Always preserve a Markdown handoff artifact for plan unless the user explicitly says no plan handoff is needed:

plans/YYMMDD-{slug}/
  brainstorm.md

The artifact path is plans/YYMMDD-{slug}/brainstorm.md. Create only the folder and this report now — do not pre-create evidence/, reviews/, fixes/, or ship/. Later steps (plan, cook, fix, ship) create those subfolders when they actually write into them, so an abandoned brainstorm leaves no empty scaffolding. Prefer colocating brainstorm output with the future plan so those artifacts land beside it.

Sections:

1. Problem statement
2. Scout report summary — repo context and local unknowns
3. Discovery — confirmed intent and implicit standards
4. Scope — minimum useful version, Not Doing, success boundary
5. Web research — source notes, external tradeoffs, or explicit skip reason
6. Analysis — 2-3 directions with Pros/Cons and YAGNI/KISS/DRY evaluation
7. Debate — brutal-honesty challenge and recommendation
8. Consensus — chosen direction, rationale, accepted tradeoffs
9. Hidden assumptions — Must / Should / Might be true
10. Success metrics — testable, not vague
11. Next steps

Format behavior:

• markdown: write brainstorm.md only.
• html: write brainstorm.md, then run preview --html against the

work-item folder or brainstorm.md. preview owns visual route selection, visual-route.md, and showcase.html:

plans/YYMMDD-{slug}/
  brainstorm.md
  visuals/
    visual-route.md
    showcase.html

• another explicitly requested format: write it if it is clear and useful;

keep brainstorm.md as the canonical handoff summary unless the user opted out of planning.

Do not write brainstorm.html from brainstorm. HTML is a preview artifact owned by preview, so the brainstorm report stays canonical and the visual output remains grounded in the written consensus.

Step 8 - Handoff

After approval and written report, offer:

1. plan --tdd plans/YYMMDD-{slug}/brainstorm.md — plan with tests-first phases
2. plan plans/YYMMDD-{slug}/brainstorm.md — standard plan with Design Contract
3. End session

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: danielleit241
• Source: danielleit241/forge
• License: ISC

Install and usage instructions live in the source repository linked above.