brainstorm

name	brainstorm
description	Interactive idea maturation — explore, research, shape raw ideas into actionable plans. Use when you have a rough idea and want to think it through.
effort	high
model	sonnet
keywords	["idea","explore","challenge","shape","opportunity","maturation"]
task_strategies	["spike","feature"]
stream_affinity	["roadmap","research","experiments"]
argument-hint	[idea or topic]
group	thinking
allowed-tools	["Read","Glob","Grep","Bash","Write","Edit","Agent","WebSearch","WebFetch","AskUserQuestion","Task","TaskList","Skill","mcp__context7__resolve-library-id","mcp__context7__query-docs","mcp__ruflo__memory_search","mcp__ruflo__memory_store","mcp__ruflo__agent_spawn","mcp__ruflo__hive-mind_shutdown","mcp__ruflo__hive-mind_init","mcp__ruflo__hive-mind_spawn","mcp__ruflo__hive-mind_consensus","ToolSearch"]
status	stable
growth_stage	evergreen

Brainstorm

Interactive idea maturation. You have a rough idea — this skill helps you explore it, research what exists, challenge assumptions, and shape it into something concrete.

Usage

/brana:brainstorm [idea]

• With idea: start exploring immediately
• Without idea: ask what's on your mind

Principles

1. The user leads. They own the idea. You research, challenge, and structure — never hijack.
2. Interactive always. Every phase uses AskUserQuestion for direction. Never monologue.
3. Research proactively. When a tool, framework, or concept is mentioned, auto-fetch context.
4. Diverge then converge. First widen (explore angles), then narrow (pick direction).
5. Concrete over abstract. Push toward specifics — who, what, how, when.

Step Registry

On entry, create a CC Task step registry. Follow the guided-execution protocol.

Register these steps: LOAD, SEED, EXPAND, DISCUSS, SHAPE, OUTPUT, EXTRACT, EVALUATE, PERSIST.

ToolSearch("select:mcp__ruflo__memory_search,mcp__ruflo__agent_spawn,mcp__ruflo__hive-mind_init,mcp__ruflo__hive-mind_spawn,mcp__ruflo__hive-mind_consensus,mcp__ruflo__hive-mind_shutdown,mcp__brana__agy_delegate")

Procedure

Step 0 — LOAD

Pull relevant knowledge into context before the brainstorm begins. Budget: 30K tokens max.

1. Build query from available context: "{project} {task.subject} {task.tags joined} {user_input}"
2. Primary — ruflo MCP (run both in parallel — namespace: "all" only returns session records; specs namespace is unindexed):

   mcp__ruflo__memory_search(query: "{query}", namespace: "knowledge", limit: 4, threshold: 0.4)
   mcp__ruflo__memory_search(query: "{query}", namespace: "pattern",   limit: 3, threshold: 0.4)
   

   Merge results, rank by similarity. Focus on: dimension docs, idea docs (docs/ideas/), and recent research findings. 2b. Graph edge traversal — see build.md LOAD step 2b. Follow depends_on/informs edges from knowledge results. Max 3 graph-derived docs. Best-effort, never blocks.
3. Fallback — tag-based grep (if MCP unavailable):

   grep -rl "{keywords}" ~/enter_thebrana/brana-knowledge/dimensions/ --include="*.md" | head -5
   grep -rl "{keywords}" docs/reflections/ docs/ideas/ --include="*.md" | head -5
   

   Read the top 3 matching files (first 80 lines each).
4. Skill match handling — if any result has namespace: "skills" and score >= 0.5, mention inline: "Matching skill: /brana:{name} ({score})." Informational only — don't auto-invoke or block. 4a. JIT skill acquisition — if no skills match and topic involves a specific technology, offer marketplace search via Skill(skill="brana:acquire-skills", args="{tech}"). Read installed procedure into context immediately. See build.md LOAD step 4a for full logic and guard rails.
5. Summarize loaded knowledge as a brief context preamble (2-5 bullets). Do not show raw results — synthesize what's relevant to the seed idea.

Phase 1 — Seed

Parse $ARGUMENTS:

• If provided: use as the seed idea, proceed to Phase 2
• If empty: ask the user

AskUserQuestion:
  question: "What's the idea you want to explore?"
  header: "Seed"
  options:
    - "A product or feature"        → "What problem does it solve?"
    - "A business opportunity"      → "Who's the customer?"
    - "A process improvement"       → "What's broken today?"
    - "Something else"              → free text

Capture the seed. Restate it back in one sentence to confirm understanding.

If --goal was passed, derive the slug (lowercase, hyphenated from the seed) and call /goal:

/goal "brainstorm {slug}: explore → challenge → shape → save — idea doc committed at docs/ideas/{slug}.md"

Then write ~/.claude/run-state/active-goal.json:

{"task_id": "{task_id_if_known_or_omit_field}", "cwd": "{git_root}", "session_id": "$BRANA_SESSION_ID", "criteria": ["file docs/ideas/{slug}.md exists"]}

The Stop hook (goal-completion.sh) will auto-complete the task when the idea doc is committed.

Phase 2 — Expand

Explore the idea space. Run these in parallel:

2a. Context scan — search the codebase and project docs for related work:

• Grep for keywords from the seed across docs/, system/, and tasks.json
• Check if related tasks already exist in the backlog
• Report: "Found N related items" (list briefly)

2b. Auto-research — if the seed mentions any tool, platform, framework, or technical concept:

• Spawn a scout agent via ruflo for cost tracking:

  mcp__ruflo__agent_spawn(agentType: "Explore", model: "haiku", domain: "{active_project}", task: "Search codebase for: {seed keywords}")
  

  Fall back to Agent(subagent_type: "Explore", model: "haiku") if ruflo is unavailable.
• Run WebSearch for the concept (1-2 queries max)
• Summarize findings in 3-5 bullets
• If a library is mentioned, use context7 MCP to get latest docs

2c. Ask for dimensions — use AskUserQuestion:

AskUserQuestion (batch up to 4 questions):

  question: "Who benefits most from this?"
  header: "Audience"
  options: [contextual — inferred from the seed]

  question: "What's the scale? Quick experiment or long-term investment?"
  header: "Scale"
  options:
    - label: "Quick experiment (hours/days)"
      description: "Low-commitment exploration — validate before committing resources."
    - label: "Small project (1-2 weeks)"
      description: "Well-scoped project; fits in a sprint or two."
    - label: "Significant investment (weeks+)"
      description: "Multi-week commitment requiring planning and phasing."
    - label: "Not sure yet"
      description: "Scale unclear — explore more before estimating."

  question: "What does success look like?"
  header: "Success"
  options: [contextual — inferred from the seed, e.g., "Revenue", "Time saved", "User engagement", "Learning"]

  question: "Any constraints or non-negotiables?"
  header: "Constraints"
  options:
    - label: "Budget limited"
      description: "Cost is a hard constraint — prioritize cheap solutions."
    - label: "Time pressure"
      description: "Deadline is fixed — scope must fit the time."
    - label: "Must integrate with existing system"
      description: "Compatibility with existing system is non-negotiable."
    - label: "None / not sure"
      description: "No hard constraints identified yet."

2d. JTBD lens — if the seed is a product, feature, or user-facing change, apply the jobs-to-be-done frame before moving to Phase 3:

Construct a job statement from what the user shared:

When [situation], I want to [motivation], so I can [outcome].

Then map the three dimensions inline (no AskUserQuestion — derive from context):

• Functional: what they literally need to do
• Emotional: how they want to feel while doing it
• Social: how they want to be perceived afterward

Present it and probe: "The job as I read it: [job statement]. Does this ring true, or is there a deeper job underneath?" If the user corrects it, update before continuing. Skip this step for purely technical ideas (internal tools, refactors, infra) where there is no end-user job to identify.

Phase 3 — Discuss & Challenge

This is the core of the brainstorm — an interactive back-and-forth dialogue. Not a list of risks. A real conversation where you push back, ask hard questions, and help the user stress-test their thinking.

This phase loops until the user is ready to move on.

Round 1 — Proactive challenge

Pick the weakest assumption in the idea so far. State it directly, then ask:

AskUserQuestion:
  question: "You're assuming {assumption}. What if that's wrong?"
  header: "Challenge"
  options:
    - "Good point — let me rethink"     → discuss alternatives together
    - "I've validated this because..."  → user defends, you probe deeper
    - "It's a bet I'm willing to take"  → acknowledge, move to next challenge
    - "Actually, let me explain..."     → free text, then respond to their reasoning

Respond to their answer. Don't just acknowledge — engage:

• If they rethink: suggest 2 alternative approaches, ask which resonates
• If they defend: ask a follow-up that tests the defense ("How would you know if...")
• If they accept the risk: name what failing would look like, ask if that's survivable

Round 2 — Flip the perspective

Take the opposite position. If the user wants to build something, argue for buying. If they want to go fast, argue for going slow. If they want simple, argue for comprehensive.

State the counter-position in 2-3 sentences, then:

AskUserQuestion:
  question: "Playing devil's advocate: {counter-position}. What's wrong with this argument?"
  header: "Counter"
  options:
    - label: "That's actually a good point"
      description: "Explore the counter-position together."
    - label: "Here's why that won't work..."
      description: "Defend your approach with free text."
    - label: "Both could work — help me decide"
      description: "Run a comparative analysis of the two approaches."
    - label: "Skip — I'm confident in my direction"
      description: "Bypass this challenge and proceed as planned."

Round 3+ — Follow the thread

Based on the discussion so far, either:

A) Drill deeper — if an interesting tension surfaced, explore it:

• "You said {X} but earlier you said {Y} — how do those fit together?"
• "What would {audience} say about this?"
• "If you had to cut one thing, what goes?"

B) Widen the lens — if the idea survived all challenges without contradiction, explore adjacent territory:

• "Who else has tried something like this? What happened?"
• "What's the version of this that's 10x simpler?"
• "What would make this a must-have instead of a nice-to-have?"

Each round uses AskUserQuestion with contextual options. Keep rounds short — one question at a time, real responses, not lectures.

Pre-mortem round (run once, after challenges converge)

When Round 1–2 challenges are done and the idea is still standing, run a lightweight pre-mortem before exiting Phase 3. This is not a full /brana:pre-mortem — it's a 60-second prospective hindsight pass.

Say: "One more thing before we shape this: imagine it's 6 months from now and this completely failed. What went wrong?"

Rapidly generate 4–6 failure causes across these lenses (silently, don't list them to the user — select the 2 most credible):

Lens	Failure prompt
Technical	What broke, couldn't scale, or had a hidden dependency?
Assumptions	Which core assumption was wrong?
Market/context	What changed that made this irrelevant or untimely?
Execution	What did we fail to actually ship or follow through on?

Surface the top 2 as a pair:

AskUserQuestion:
  question: "Pre-mortem: if this failed in 6 months, the most likely reasons would be [Risk A] or [Risk B]. Which worries you more?"
  header: "Pre-mortem"
  options:
    - label: "[Risk A] — most likely"
      description: "Acknowledge and discuss a mitigation."
    - label: "[Risk B] — most likely"
      description: "Acknowledge and discuss a mitigation."
    - label: "Neither — here's what I'm actually worried about"
      description: "Free text — user names the real risk."
    - label: "Neither — I've addressed both"
      description: "User has already mitigated these; proceed to shape."

Note the top risk in the idea doc (docs/ideas/{slug}.md) under ## Risks before moving to the Exit.

Exit

After each round, offer an exit:

AskUserQuestion:
  question: "Keep discussing, or ready to shape this into something concrete?"
  header: "Continue?"
  options:
    - label: "Keep going — I want to explore {aspect}"
      description: "Continue the discussion on a specific aspect of the idea."
    - label: "Challenge me harder on {topic}"
      description: "Push back more forcefully on a specific assumption."
    - label: "Ready to shape it (Recommended)"
      description: "Move to Phase 4 and turn the idea into a concrete doc."
    - label: "Let me think — save what we have"
      description: "Save current state and jump to Phase 5 without shaping."

If the user mentions a new concept during any round, auto-research it (WebSearch, 1 query) and fold findings into the next response before asking the next question.

3b — Incremental persistence

After each round (Round 1 always, Round 2+ whenever new ground was covered):

1. If docs/ideas/{slug}.md does not exist yet: create it now with the frontmatter stub and the first section derived from what was just discussed.

   ---
   title: {Title}
   status: idea
   created: {date}
   ---
   # {Title}
   > Brainstormed {date}. Work in progress.
   

2. If it already exists: append or update the relevant section (Problem, Solution, Risks, etc.) based on the current discussion.
3. Tell the user: "Saved to docs/ideas/{slug}.md — continuing."

The doc grows section-by-section throughout Phase 3. By the time Phase 5 runs, most content is already written. Context compression cannot lose discussion output because it was persisted immediately.

Discussion behavior rules

• One question at a time. Never stack 3 challenges — ask one, respond, ask the next.
• React to their answers. Reference what they said. "You mentioned X — that changes things because..."
• Escalate, don't repeat. Each round goes deeper than the last. Never re-ask the same challenge.
• Name your role. Say "Playing devil's advocate here..." or "Pushing back on this..." so the user knows you're challenging, not disagreeing.
• Acknowledge strong defenses. When the user addresses the specific objection with evidence or logic, say so: "That answers the [specific concern] — it holds up because [reason]."
• Research mid-discussion. If the user mentions a competitor, tool, or reference you don't know, search for it immediately and bring findings into the next question.

Phase 4 — Shape

Synthesize everything into a structured summary. Present it as a preview:

## Idea: {title}

**Problem:** {one sentence}
**Solution:** {one sentence}
**Audience:** {who}
**Scale:** {effort level}
**Success metric:** {what good looks like}

### Key insights from research
- {finding 1}
- {finding 2}
- {finding 3}

### Risks and mitigations
- {risk → mitigation}

### Engineering disciplines
- **DDD (Decision):** {ADR needed? What architectural decision does this encode?}
- **TDD (Tests):** {What tests should be written before implementation?}
- **SDD (Spec/Docs):** {What docs need updating after implementation?}
- **Docs (/brana:docs):** {Which doc types apply per strategy table below?}
  - Tech doc: `docs/architecture/features/{slug}.md` — {yes/no, why}
  - User guide: `docs/guide/features/{slug}.md` — {yes/no, why}
  - Shared docs: `docs/guide/commands/index.md` updates? workflow docs? — {list}
  - Overview: `docs/guide/philosophy.md` — {only if system-level patterns changed}
  - Spec-graph routing: {files whose `impl_files` overlap with expected changes}

### Possible next steps
1. {step 1}
2. {step 2}
3. {step 3}

4b. Second-order trace — before presenting the review question, run a quick consequence chain on the top 1–2 next steps in the SHAPE summary above.

For each: "If we do [step], what happens directly? And then what?"

Step → 1st-order effect
1st-order effect → 2nd-order consequence (behavioral / competitive / resource / systemic / temporal)

Identify the most surprising 2nd-order finding — one that isn't obvious from the step itself. If it's a risk, flag it. If it's an opportunity, name it. Add a ### Second-order effects section to the idea doc and to the SHAPE summary:

### Second-order effects
- [Step] → [1st order] → [2nd order surprise — risk or opportunity]
- [Step] → [1st order] → [2nd order surprise — risk or opportunity]

Skip this step if the top next steps are trivial (e.g., "write a spec", "talk to a user") with no meaningful downstream chain.

Then ask:

AskUserQuestion:
  question: "How does this look? What should we adjust?"
  header: "Review"
  options:
    - label: "Looks good — save it (Recommended)"
      description: "Save the shaped idea doc and proceed to Phase 5."
    - label: "Adjust the direction"
      description: "Loop back to a specific section for refinement."
    - label: "Research more on {topic}"
      description: "Run targeted research on a specific topic, then re-present."
    - label: "Scrap it — not worth pursuing"
      description: "Abandon the idea without saving."

Allow multiple refinement loops. Each loop re-presents the updated summary.

Phase 5 — Output

When the user approves ("Looks good — save it"):

5a. Finalize idea doc

The idea doc at docs/ideas/{slug}.md was built incrementally during Phase 3b. Phase 5 refines and completes it — it does not start from scratch. Open the existing file and:

• Fill in any sections that are still placeholders
• Replace "Work in progress" status with idea (or draft if well-formed)
• Add the full Phase 4 shape summary if not yet present

If docs/ideas/{slug}.md does not exist (brainstorm was short or Phase 3b was skipped), create it now at docs/ideas/{slug}.md:

# {Title}

> Brainstormed {date}. Status: idea.

## Problem

{problem statement}

## Proposed solution

{solution description}

## Research findings

{key findings from Phase 2}

## Risks

{risks and mitigations from Phase 3}

## Next steps

{action items from Phase 4}

5b. Plan the backlog

GATE: Check effort level from Phase 4 SHAPE. If effort is M+ (Small project / 1-2 weeks or higher):

AskUserQuestion:
  question: "This is an M+ effort. Confirm governance tasks before backlog planning?"
  header: "Governance Gate"
  options:
    - "Yes — include DDD/TDD/SDD/Docs tasks" → proceed to backlog plan
    - "Override (skip + file tech-debt task)" → skip governance tasks AND add a P2 tech-debt task to backlog: 'Add DDD/TDD/SDD/Docs coverage to {idea slug} plan'
    - "Back to SHAPE"                        → return to Phase 4 to reassess

This gate catches brainstorms that identified engineering disciplines in SHAPE but would otherwise forget to create the corresponding backlog tasks. It's the last checkpoint before planning commits the idea to structured execution.

M+ challenger review — before backlog planning, run a hive-mind 3-worker challenge on the shaped idea. Read ../_shared/adversarial-hive-mind.md for the full pattern. Caller-specific values: prefix: "brainstorm-challenger", type: "brainstorm-findings", value: "{shaped idea summary}". Findings confirmed by ≥2 workers surface as HIGH confidence — present these before the backlog question.

---

AskUserQuestion:
  question: "Plan this idea into the backlog?"
  header: "Backlog"
  options:
    - label: "Yes — plan phases & tasks"
      description: "Invoke /brana:backlog plan with the idea as input."
    - label: "Not yet — just save the doc"
      description: "Save the brainstorm doc without creating backlog tasks."
    - label: "Quick add (flat task only)"
      description: "Create a single task via backlog_add() without full planning."

If "Yes — plan phases & tasks" (default, recommended): Invoke /brana:backlog plan via the Skill tool immediately:

Skill(skill="brana:backlog", args="plan \"{idea title}\"")

The plan skill will interactively create the full phase/milestone/task hierarchy using the brainstorm's phased rollout as input. This is the mandatory default — a brainstormed idea with phases and next steps deserves structured planning, not a flat task.

DDD/TDD/SDD/Docs tasks are mandatory when planning. For any effort M+ idea, the planned phase must include:

• DDD task: Write an ADR documenting the decision (before implementation tasks)
• TDD tasks: Write tests before implementation (blocked_by: ADR, blocks: impl tasks)
• SDD tasks: Update specs that the implementation changes (blocked_by: impl tasks)
• Docs tasks: Generate living docs via /brana:docs strategy (blocked_by: impl tasks). Use the /brana:docs all strategy table to determine which doc types apply:
  • feature/greenfield: tech doc + user guide + shared doc updates + overview (if system-level)
  • migration: tech doc + user guide + overview (if architecture changed)
  • refactor: tech doc only (if architecture changed)
  • bug-fix: skip docs entirely Each applicable doc type becomes a task (or one combined /brana:docs all task). Include spec-graph routing candidates as a checklist in the docs task context.
• Dependency order: ADR → tests → implementation → specs + docs → validation

These come from the "Engineering disciplines" section in the SHAPE summary. If that section identified specific ADRs, test strategies, docs, or spec-graph routing targets, turn each into a concrete task with proper blocked_by relationships enforcing the DDD → TDD → impl → SDD + docs flow.

If "Quick add (flat task only)" (escape hatch for trivial ideas): Create a single task via backlog_add() (MCP) or brana backlog add with:

• Subject from idea title
• Description from problem + solution
• Context linking to the idea doc
• Tags inferred from the brainstorm content
• Stream: roadmap (default) or research (if chosen)

5c. Report

Saved: docs/ideas/{slug}.md
Backlog: {phase ID + task count if planned, or t-NNN if quick-added, or "none"}

Step 6 — EXTRACT

At skill end, identify what was learned during the brainstorm session:

1. Review the brainstorm output — what facts were learned, what decisions were made, what patterns observed
2. Classify each finding using ontology entity types as vocabulary:
   • Pattern — reusable solution or approach
   • ADR — architecture decision that was made or implied
   • Dimension — new topic area worth a knowledge doc
   • FieldNote — practical gotcha or surprise
3. Skip if brainstorm was purely exploratory with no concrete findings

Step 7 — EVALUATE

Score each finding (0-10) on two axes:

Axis	SMALL (0-1)	MEDIUM (2-4)	LARGE (5+)
Scope	This brainstorm only	This project	Multiple projects/clients
Novelty	Already known	New on existing topic	New topic or contradicts existing

Gate by size:

• SMALL: Auto-persist (no prompt). Tags, URLs, task context.
• MEDIUM: Inline eval — check for duplicates via mcp__ruflo__memory_search(query: "{finding summary}", namespace: "knowledge", limit: 2) and mcp__ruflo__memory_search(query: "{finding summary}", namespace: "pattern", limit: 2). If top result similarity > 0.9, skip or merge. Present remaining to user via AskUserQuestion.
• LARGE: Present to user with recommendation via AskUserQuestion. For ADRs or cross-client patterns, suggest /brana:challenge review.

Step 8 — PERSIST

Route each accepted finding by type:

Type	Destination	Auto/Prompted
Pattern	mcp__ruflo__memory_store(namespace: "pattern") + memory file	SMALL: auto, MEDIUM+: prompted
ADR	Draft in docs/architecture/decisions/	Always prompted
Dimension	Note for brana-knowledge/dimensions/	Always prompted
FieldNote	Append to relevant dimension doc ## Field Notes	MEDIUM: prompted
Tags/URLs/context	Task context field	Auto

For ruflo stores, use:

mcp__ruflo__memory_store(
  key: "pattern:{PROJECT}:{slug}",
  value: '{"finding": "...", "source": "brainstorm", "confidence": 0.5}',
  namespace: "pattern",
  tags: ["client:{PROJECT}", "source:brainstorm"],
  upsert: true
)

If ruflo unavailable, write to ~/.claude/projects/{project}/memory/ as markdown file.

Anti-patterns

• Don't monologue. If you've written more than 2 paragraphs without asking a question, stop and ask.
• Don't over-research. 1-2 web searches per concept, not 10. The goal is grounding, not exhaustive review.
• Don't force convergence. If the user wants to keep exploring, let them. The shape phase waits.
• Don't skip the challenge. Even if no obvious flaws exist, present at least 2 counterarguments (market risk, execution complexity, alternative approaches).
• Don't create tasks without asking. The idea doc is always written. The task is always offered, never auto-created.
• Step registry. Follow the guided-execution protocol. Register steps on entry, update as each completes.

---

Resume After Compression

If context was compressed and you've lost track of progress:

1. Call TaskList — find CC Tasks matching /brana:brainstorm — {STEP}
2. The in_progress task is your current phase — resume from there
3. Check docs/ideas/ for any idea doc already written (Phase 5)