| name | mx-brainstorm |
| description | Turn a rough idea into an approved design spec before any code is written: one question at a time, 2-3 distinct approaches with trade-offs, spec and ADR written to ~/.mx/<project>/<name>/. Hard gate: no implementation until the user approves the spec. Use at the start of any feature or non-trivial fix.
|
| author | Maxence Yang |
| github | https://github.com/maxence2997/mx-harness |
| source | https://github.com/maxence2997/mx-harness/tree/main/mx-brainstorm |
| user-invocable | true |
| allowed-tools | ["Bash","Read","Glob","Grep","Write"] |
mx-brainstorm
Trigger
/mx-brainstorm <topic>
/mx-brainstorm
Operating principles
Don't assume. Don't hide confusion. Surface tradeoffs. These apply at
every step below — not just Step 1.
- State assumptions explicitly. If uncertain, ask rather than guess.
- Present multiple interpretations. When the user's request is
ambiguous, surface the readings and let the user pick. Do not silently
choose one and proceed.
- Push back when warranted. If a simpler approach exists, say so. If a
proposed option is over-engineered for the stated problem, name it.
- Stop when confused. Name what is unclear and ask for clarification.
Do not paper over confusion with plausible-sounding text.
Applied to this skill specifically:
- In Step 2, options must be genuinely distinct — do not pad to three
options by inventing a contrived variant. Two real options beats three
fake ones.
- In Step 2, prefer the minimum approach that solves the stated
problem. Larger options must justify their extra scope explicitly in
Best when.
Side requests
At any step, the user may ask for something mid-conversation (e.g. "open
an issue", "add a comment", "check a file"). When this happens:
- Execute exactly what was requested — nothing more
- Do not make additional code changes, file edits, or actions that were
not asked for
- After completing the side request, return to the brainstorm conversation
Example: "go open an issue describing this" → open the issue, stop. Do not
also edit source files.
Step 1 — Understand the idea
Read existing code relevant to the topic (if any) using Glob and Read.
Then ask the user one question at a time to clarify:
- What problem does this solve?
- Who is affected and how?
- Are there constraints (performance, compatibility, deadlines)?
- What does success look like?
Rules:
- One question per message — never bundle multiple questions
- Prefer multiple-choice over open-ended where possible
- There is no question limit — keep asking until the picture is genuinely
clear
- If invoked from mx-flow, the topic is already provided — begin with the
first clarifying question immediately, do not ask if the user wants to
start
When you believe you have enough context, ask before proposing approaches:
I think I have a clear enough picture. Anything else you'd like to clarify,
or shall we move on to exploring approaches?
Do not proceed to Step 2 until the user confirms.
Step 2 — Propose approaches
Present 2 or 3 distinct approaches. For each:
### Option A — <short name>
What: <one sentence>
Trade-offs: <pros and cons>
Best when: <the condition that makes this the right choice>
Do not recommend one option as "best" — let the user decide.
If you have a strong preference based on the context, state the reason
once, briefly.
Step 3 — Refine
Ask follow-up questions one at a time if the user's choice reveals new
ambiguities. Iterate until the design is unambiguous.
Hard gate: do not proceed to Step 4 until the user explicitly approves
the design spec. This gate stays human even when invoked from an
orchestrator — it is mx-flow's GATE 1.
Step 4 — Write the design spec
Resolve the MX directory:
- Get the repo root name: final path component of
git rev-parse --show-toplevel
- MX =
~/.mx/<project>/ (Unix) or %USERPROFILE%\.mx\<project>\ (Windows)
- Create
MX/<name>/ if it does not exist
Create MX/<name>/spec.md.
Spec format:
# <feature-name> — Spec
## What
<What is being built or changed — one paragraph>
## Why
<The problem it solves and why it matters>
## How
<The chosen approach, key design decisions, trade-offs accepted>
## Out of scope
<Explicitly list what this change does NOT cover>
Show the design spec to the user for final review. Allow adjustments.
Step 5 — Record ADR
After the spec is confirmed, automatically write the ADR without asking.
Read references/adr-format.md (located in the same directory as this
SKILL.md) for the format and rules. Populate from the brainstorm
conversation and append to MX/<name>/adr.md.
Report: ADR saved to ~/.mx/<project>/<name>/adr.md
Step 6 — Hand off
Once the design spec and ADR are saved, announce:
Design spec saved to ~/.mx/<project>/<name>/spec.md
ADR saved to ~/.mx/<project>/<name>/adr.md
Ready for /mx-flow — this will decompose the spec into tasks and continue the workflow.
Do not invoke mx-flow automatically. The user invokes it.
