Brainstorming
Overview
Refine a design collaboratively before any code or plan exists. Walk through the
design one section at a time, always leading with a concrete recommendation, and
validate each section with the partner before moving on. The goal is a design the
partner fully understands and can defend, not a design handed to them fully formed.
Announce at start: "I'm using the brainstorming skill to work through this design with you."
Core Rules
These are the heart of the skill, follow them on every turn:
Every question MUST include a recommendation. Lead with "I'd lean toward X
because Y. Does that match your thinking?", never an open-ended "what do you
think?". The partner is validating or redirecting a proposal, not staring at a
blank page. This is what keeps momentum and teaches the reasoning as you go.
One question at a time. Don't overwhelm. Ask, wait, incorporate the answer,
then ask the next. This means one question per turn, not one decision question
with a second "and also…" tacked on the end. If you need context before you can
recommend, that context question IS the turn: ask it alone and wait. Resist the
pull to gather background and validate a decision in the same message; splitting
them is what keeps the partner in control and each answer unambiguous.
Multiple choice preferred where it fits. Offer A / B / C options, each with
its trade-off named, so the choice is concrete and the partner can weigh it.
Present the design in small sections (200-300 words each). Validate after each
section before drafting the next. Small increments keep the partner in control and
surface disagreement early, while it's cheap.
Explore 2-3 alternatives before settling on any choice, and name the
trade-off explicitly. A recommendation with no alternative is an assertion; a
recommendation with the runner-up and the reason is a decision the partner can own.
YAGNI ruthlessly. Cut features not required for the actual goal. If it isn't
needed for the stated objective, it doesn't go in the design.
Be flexible. If something doesn't make sense, go back and clarify. The
section-by-section structure is a guide, not a cage, revisit earlier decisions
when a later one exposes a problem.
Working Pattern
For each section of the design:
- State the recommendation up front, with a one-line reason.
- Give 2-3 alternatives with their trade-offs (multiple-choice where possible).
- Explain the chosen tech in enough depth that the partner can defend it live, not
just what, but why, and how it compares to the obvious textbook alternative.
- Ask a single validating question.
- Wait for the answer. Incorporate it. Move to the next section only once validated.
Deliverable
At the end of the session, produce a DESIGN.md:
- If
--output-dir provided: write to {OUTPUT_DIR}/DESIGN.md
- Otherwise: write to
docs/plans/YYYY-MM-DD-DESIGN-<topic>.md
The DESIGN.md is the artifact the partner keeps (and may convert to PDF via Cmd-P for
sharing). It should capture, per section: the decision made, the alternatives
considered, and the trade-off that justified the choice, so the reasoning survives,
not just the conclusion.
Handoff
After the design is validated and DESIGN.md is saved, offer the next step:
optionally produce a PLAN.md via writing-plans, which turns the design into a
task-by-task implementation plan.
Related Skills
| Skill |
When to Use |
writing-plans |
After the design is settled, turn DESIGN.md into an implementation plan |
executing-plans |
After a plan exists, implement it in batches |
skeptic |
To pressure-test the design's necessity and scope before committing |
1---2name: brainstorming3description: Collaborative, one-question-at-a-time design brainstorming that walks through a system or feature design section by section, always leading with a recommendation, and produces a DESIGN.md at the end. Use when the solution is unclear and needs design refinement first, when asked to "brainstorm", "help me design", "work through a design", "think through the architecture", or before writing an implementation plan. Precedes writing-plans.4---56# Brainstorming78## Overview910Refine a design collaboratively before any code or plan exists. Walk through the11design one section at a time, always leading with a concrete recommendation, and12validate each section with the partner before moving on. The goal is a design the13partner fully understands and can defend, not a design handed to them fully formed.1415**Announce at start:** "I'm using the brainstorming skill to work through this design with you."1617## Core Rules1819These are the heart of the skill, follow them on every turn:20211. **Every question MUST include a recommendation.** Lead with "I'd lean toward X22 because Y. Does that match your thinking?", never an open-ended "what do you23 think?". The partner is validating or redirecting a proposal, not staring at a24 blank page. This is what keeps momentum and teaches the reasoning as you go.25262. **One question at a time.** Don't overwhelm. Ask, wait, incorporate the answer,27 then ask the next. This means one question *per turn*, not one decision question28 with a second "and also…" tacked on the end. If you need context before you can29 recommend, that context question IS the turn: ask it alone and wait. Resist the30 pull to gather background and validate a decision in the same message; splitting31 them is what keeps the partner in control and each answer unambiguous.32333. **Multiple choice preferred** where it fits. Offer A / B / C options, each with34 its trade-off named, so the choice is concrete and the partner can weigh it.35364. **Present the design in small sections** (200-300 words each). Validate after each37 section before drafting the next. Small increments keep the partner in control and38 surface disagreement early, while it's cheap.39405. **Explore 2-3 alternatives** before settling on any choice, and **name the41 trade-off** explicitly. A recommendation with no alternative is an assertion; a42 recommendation with the runner-up and the reason is a decision the partner can own.43446. **YAGNI ruthlessly.** Cut features not required for the actual goal. If it isn't45 needed for the stated objective, it doesn't go in the design.46477. **Be flexible.** If something doesn't make sense, go back and clarify. The48 section-by-section structure is a guide, not a cage, revisit earlier decisions49 when a later one exposes a problem.5051## Working Pattern5253For each section of the design:541. State the recommendation up front, with a one-line reason.552. Give 2-3 alternatives with their trade-offs (multiple-choice where possible).563. Explain the chosen tech in enough depth that the partner can defend it live, not57 just what, but why, and how it compares to the obvious textbook alternative.584. Ask a single validating question.595. Wait for the answer. Incorporate it. Move to the next section only once validated.6061## Deliverable6263At the end of the session, produce a **`DESIGN.md`**:6465- **If `--output-dir` provided:** write to `{OUTPUT_DIR}/DESIGN.md`66- **Otherwise:** write to `docs/plans/YYYY-MM-DD-DESIGN-<topic>.md`6768The DESIGN.md is the artifact the partner keeps (and may convert to PDF via Cmd-P for69sharing). It should capture, per section: the decision made, the alternatives70considered, and the trade-off that justified the choice, so the reasoning survives,71not just the conclusion.7273## Handoff7475After the design is validated and `DESIGN.md` is saved, offer the next step:76optionally produce a `PLAN.md` via `writing-plans`, which turns the design into a77task-by-task implementation plan.7879## Related Skills8081| Skill | When to Use |82|-------|-------------|83| `writing-plans` | After the design is settled, turn DESIGN.md into an implementation plan |84| `executing-plans` | After a plan exists, implement it in batches |85| `skeptic` | To pressure-test the design's necessity and scope before committing |
maccydee