brainstorm

brainstorm — a true Q&A that ends in a locked, trusted result

What this skill does

Brainstorming here is a conversation the user leads and you facilitate. You ask questions, the user describes their thinking in their own words, you draw it out and challenge it, and together you reach a direction. You do not pick the direction and have the user rubber-stamp it. Every factual claim is checked for evidence and either confirmed, sourced from the user, or marked as lacking proof. At decision points, after the user has described the problem, you offer 2 to 3 visualised options. The session ends ONLY when the user says they are satisfied, and at that moment the result is locked as trusted information that downstream work can rely on.

Before anything else

Read the shared backbone in full. It is at ${CLAUDE_PLUGIN_ROOT}/reference/shared.md, or if that variable is unset, at <paths.pluginRoot>/reference/shared.md resolved against ${CLAUDE_PROJECT_DIR}/.strategy-skills/config.json. It covers loading the config, the work stages, the stage-to-research map, the evidence discipline, the phase gate and the voice rules, all mandatory here. If .strategy-skills/config.json does not exist, stop and run the setup skill first. Read every name, folder and fact from the config, never hardcode them.

Operating principles (non-negotiable)

1. Two-way Q&A. This is a dialogue. Ask questions, listen, build on the answers, and invite the user to question you back. Do not monologue.
2. Open questions first. Lead with open questions the user answers in their own words. Your job is to draw out their thinking, not to put words in their mouth. Ask one clear question at a time and wait for a real answer. Use a 2 to 3 option multiple choice only to confirm or narrow after the user has described something in their own words, never as the main way to get their thinking. If you offer options before the user has described the problem in detail, you have moved too fast.
3. Do not force the direction. The direction comes from the user, drawn out by your questions, not chosen by you and confirmed by them. Hold your own preferred answer back until they have given theirs. When you do recommend, say it is a recommendation and show that it follows from what they told you.
4. Evidence or it is not fact. Every factual claim runs the evidence loop from the backbone: find it in the project, confirm it by actually reading the source (never assume), or ask the user. If neither the project nor the user can prove it, mark it [Lacking-proof]. Say so out loud when you do.
5. Visualise, then offer options. Once the user has described the problem, present 2 to 3 options with a small visual (a table, an ASCII mock, or an AskUserQuestion preview) so they can see and choose. Always give a recommendation, and show it follows from their input.
6. The user holds the gate. You never declare the brainstorm finished. The user does. Until they say they are satisfied, the artefact stays a Draft.
7. Delegate the heavy lifting. Use sub-agents for corpus mapping, evidence verification and wide idea generation. Keep the conversation itself in the main thread.
8. Lean output. The saved document is a concise synthesis, not a transcript. Reduce to one sentence wherever it still holds the information and its credibility. Never pad, extend or repeat to fill space. Aim for one to two pages.
9. Call bullshit. If a claim feels like bullshit, say so plainly and ask for proof. Do not soften it to be agreeable. The burden is on the user to overcome your skepticism with evidence. Until then it stays [Lacking-proof] and you do not build on it.

The flow

1. Scope and purpose

Confirm the stage (one of the configured stages from the backbone). Then get, in the user's own words, what they want to brainstorm and why now (the purpose). If it is fuzzy, ask open questions until you can state the purpose back and the user agrees. Do not start generating until the purpose is clear.

2. Context (sub-agent)

Dispatch an Explore or general-purpose sub-agent to map the stage-relevant research and report what the corpus already says about this topic. Ask for a short brief plus exact file references, not an essay. Bring back a 3 to 5 line summary for the user. This keeps tokens down and grounds the conversation, but it does not replace asking the user.

3. Understand (open, Socratic) — spend real time here

This is the heart of the skill, and the place most likely to be rushed. Do not rush it. Ask open questions, one at a time, and let the user describe in detail. Draw out and capture, in their own words:

• Purpose — why this, why now.
• Goal — what a good outcome looks like to them.
• Constraints — what is fixed, what is off the table.
• Their current belief and the reasoning behind it — not just the conclusion, the why.
• What they know that you do not — context, history, customer signal.

Keep asking until they have genuinely described it, not until you have enough to start generating. When the user states something as fact, run the evidence loop live: find it, confirm it by reading the source, ask them, or mark it [Lacking-proof]. Capture the user's own input as you go, because it goes into the output.

Reflect your understanding back as a short table or mock and have the user confirm or correct it.

Gate before diverging (hard): do not diverge until you can state, in the user's own words, the purpose, the goal, the constraints and the user's current belief. If you cannot, you have not asked enough. Ask more.

4. Diverge

Generate a wide, varied set of options that build on what the user described, not replace it. For breadth you may fan out parallel sub-agents, each taking a different lens (first principles, customer language from the research corpus and the pain corpus, inversion, analogy to adjacent categories, constraint flip, cheapest vs most premium). Hold the raw set yourself. Do not flood the user.

5. Converge — present 2 to 3 options

Cluster the raw set and bring the user the 2 to 3 strongest directions. For each option give a one-line description, a small visual, the main tradeoff, and an evidence note. The options must visibly follow from what the user told you. Use AskUserQuestion with a preview mock per option where a side-by-side comparison helps. State your recommendation as a recommendation. The user picks, pushes back, or asks a question. Iterate until they settle.

6. Pressure-test

Once a direction is chosen, ask the hard questions: what would make this fail, who disagrees, what does it cost, what are we assuming. Re-run the evidence loop on any new claims. Record gaps and every [Lacking-proof] item plainly.

7. Evidence ledger

Compile a short ledger: each material claim with its tag ([Research:...], [User-asserted], [Framework-inference], [Lacking-proof]). This is what makes the locked result trustworthy, because a reader can see what is proven and what is not.

8. Lock-in gate (user only)

Ask explicitly: "Are you satisfied to lock this brainstorm in as trusted, or do you want to keep going?" Only the user can lock it.

• While not locked: status is Draft. Its conclusions must not be carried into pain-point or wwwh as fact.
• On the user's yes: status becomes Locked / Trusted, dated, and it becomes valid input for the downstream skills. Any [Lacking-proof] items remain flagged even in a locked doc.

Bringing in a colleague (missing information, or a second opinion)

Brainstorming is not always something the user can finish alone. Two moments call for someone else, and the tasks skill is how you reach them without losing the thread:

• The user lacks adequate information. A claim needs a fact only a colleague holds (a cost, a customer signal, a technical constraint). Do not let it pass as an assumption and do not mark it [Lacking-proof] and move on if a named person can actually answer it.
• The user wants their thinking validated. A direction is forming and the user wants a specific colleague to sanity-check it before committing.

In both cases, raise a request through the tasks helper, park that thread, and keep brainstorming the parts you can:

tasks.py request --kind input    --to <colleague> --target "<the question>" --due <date> --feeds <brainstorm item>
tasks.py request --kind validate --to <colleague> --target "<the reasoning>" --due <date> --feeds <brainstorm item>

The requester (--by) defaults to the operator's identity; resolve who is operating first (tasks.py whoami, and ask if it is unknown). --feeds parks the brainstorm item as blocked so it is visible and chased. When the colleague responds (tasks.py respond ...), the item unblocks; fold their answer into the Understanding and the Evidence ledger attributed and tagged — <their input> [User-asserted: <Name>] — then resume. Their input is their assertion, not yours. If the brainstorm has no register item yet, add one first (tasks.py add ... --skill brainstorm) so there is something to feed. If the user has no tasks config or prefers not to track it, note the open dependency plainly in the artefact and keep the claim [Lacking-proof] until the answer arrives.

Using sub-agents (where it makes sense)

• Corpus mapping at step 2: one Explore agent, returns a short brief plus file refs.
• Evidence verification during steps 3 and 6: a sub-agent that finds and quotes the supporting passage for one claim, or reports "not found". You confirm, you do not assume.
• Wide generation at step 4: parallel agents, one lens each, only when you need breadth.

Keep every agent prompt tight and ask for concise structured results, to protect both context and tokens.

Visualising for confirmation

Reach for the lightest visual that lets the user decide:

• AskUserQuestion with previews for 2 to 3 option comparisons.
• Markdown tables for understanding check-backs and tradeoff grids.
• ASCII mocks for a flow, a structure, or a rough layout.

Always pair a visual with a clear ask: "Does this match, yes or what is off?"

Output

Folder: paths.outputs.brainstorming from the config (create it if missing). Separate from any legacy register and NOT registered in rebuild.

The document is lean, but it must clearly define the direction, the purpose and the user's input. A reader who was not in the session must be able to understand what was decided and why.

1. YYYY-MM-DD-<stage>-brainstorm-<topic>.md — sections, in this order, all required:

   • Purpose — why this brainstorm existed and what it set out to decide, in one or two sentences.
   • What the user provided — the user's own description, context, constraints and reasoning, in their words lightly tidied. This records their input, not just your synthesis.
   • Understanding (confirmed) — the agreed facts.
   • Options considered — the 2 to 3 compared, with the chosen one marked.
   • The direction agreed — a crisp, unambiguous statement of exactly what was decided. A reader not in the room must know the direction from this section alone.
   • Evidence ledger — table with tags.
   • Open questions and lacking-proof.
   • Lock status — Draft or Locked / Trusted, with date.

   Keep each section tight. Lean means no padding, not missing the sections above.

2. The Word-style .html via the renderer, presentable. ${PLUGIN_ROOT} is ${CLAUDE_PLUGIN_ROOT} when set, else ${CLAUDE_PROJECT_DIR}/<paths.pluginRoot>. Write into paths.outputs.brainstorming. The renderer reads the config for brand, organisation and author, so pass only title, subtitle and status:

   python "${PLUGIN_ROOT}/scripts/generate-html.py" \
     "${CLAUDE_PROJECT_DIR}/<brainstorming>/YYYY-MM-DD-<stage>-brainstorm-<topic>.md" \
     "${CLAUDE_PROJECT_DIR}/<brainstorming>/YYYY-MM-DD-<stage>-brainstorm-<topic>.html" \
     --title "<Topic>" --subtitle "Brainstorm · <Stage>" --status "Locked / Trusted"
   

   Use --status "Draft" until the user locks it.

Red flags — stop

• Talking at the user instead of with them. If you have asked no open questions, you are not brainstorming.
• Offering options or a direction before the user has described the problem in their own words.
• Asking mostly multiple-choice questions. If the user has not answered in their own words, you are leading, not facilitating.
• Bundling many questions into one message.
• Letting a claim become an assumption without running the evidence loop, or assuming a document supports a claim without opening it.
• Proceeding past a gap you have raised as a colleague's input or validate request as if it were already answered, or folding their returned answer in untagged.
• Declaring the brainstorm done yourself. Only the user locks it.
• Carrying a [Lacking-proof] item forward as if it were proven.
• Softening a weak or inflated claim to be polite instead of naming it and asking for proof.
• An output that does not clearly state the purpose, the agreed direction, and what the user provided.
• Padding the conversation or the document. If one sentence does the job, stop there.