design-brainstorm

Files (1)

• SKILL.md

SKILL.md (first lines)

# Brainstorming Features Into Designs

Turn a rough feature idea into an approved design through collaborative dialogue, then hand the design to `/new-plan` so the existing orchestrator/executor pipeline can run it.

This is the **front half** of the Tier-3 pipeline. It sits *before* `/new-plan` and produces its inputs. It does not write code, scaffold anything, or create the plan file itself — its only output is an approved design that gets folded into the plan.

## When this fires — and when it doesn't

This skill is gated to one slice of work: **Tier-3 feature tasks with open design questions.** The tier classification that already runs on every request is the gate.

| Request | Tier | Brainstorm? |
|---------|------|-------------|
| "what does X do", "how should we approach Y" | 1 — research/Q&A | No — answer directly |
| one edit, a one-off command, a short fix | 2 — quick item | No — just do it |
| new feature / subsystem / integration with design choices to make | 3 — feature | **Yes** |
| multi-file refactor, rename, migration with a known shape | 3 — settled | No — go straight to `/new-plan` |

The distinction inside Tier 3 is **open design questions vs. settled shape.** If you already know exactly what files change and how, there is nothing to brainstorm — scaffold the plan. If there are real choices (data model, interface boundaries, where a responsibility lives, how pieces talk), brainstorm first.

If you started executing and realize the design is not actually settled, stop and invoke this.

## Two ways this skill is reached

The process below is identical regardless of how it starts. Only the **seed** differs.

1. **Auto, at the top of a request.** The tier classification routes a feature-sized request here before any plan exists. The seed is the user's request.
2. **From `/start`, on a captured task.** When the task-provider layer exists, `/start` on a captured task that is a feature with open design delegates here. The seed is the task's pulled **summary** — treat it exactly as you would an initial user request, then run the same dialogue. The summary may name an investigation (`projects/<project>/investigations/<slug>.md`), which `/start` then hands over as part of the seed. (A captured task that is quick or already settled is not sent here — `/start` takes it straight to `/new-plan`.)

In both cases the terminal handoff is the same: `/new-plan`, with the approved design folded into the plan file.

## Process

Work through these in order. Each is a step you can track in `todo.md` if the task already has one.

1. **Explore context.** Read the active project's `memory.md` (it's already injected), the relevant files, and recent commits — enough to ask a good first round, not an exhaustive survey. If you were reached from `/start`, the captured task's summary is your starting intent — read it first. Don't ask the user what the code or the summary already tells you; fetch further facts as questions need them (see *Asking questions in rounds*).
2. **Scope check.** If the request is actually several independent features ("build chat + billing + analytics"), say so before refining details. Help decompose into separate features; each gets its own brainstorm → plan cycle. Don't spend questions polishing something that needs splitting first.
3. **Clarify intent.** Ask about purpose, constraints, and what "done" looks like, in rounds (see *Asking questions in rounds*). Prefer multiple-choice when it's faster for the user. Stop asking once you can state the goal and the success criteria back accurately.
4. **Propose 2-3 approaches.** With trade-offs and a recommendation, leading with the one you'd pick and why. This is where alternatives get surfaced and rejected on the record, not silently.
5. **Present the design in sections.** Scale each section to its complexity — a sentence or two when straightforward, a paragraph when nuanced. Cover the pieces that matter: unit boundaries and interfaces, data flow, error handling, testing. Get a quick approval after each section; go back and revise when something doesn't land.

Design for clear boundaries: each unit should have one job, a well-defined interface, and be understandable and testable on its own. A file that wants to grow large is usually doing too much.

## Asking questions in rounds

Steps 3–5 put questions to the user. Ask them in **rounds** — not one at a time, not all at once.

Treat the design as a **tree**: each decision has further decisions hanging off it. The **frontier** is every open decision whose prerequisites are already settled — the questions you can ask now without guessing at an answer you haven't heard yet. Ask the whole frontier in one round, then wait. Answers settle decisions and push the frontier outward; recompute it and ask the next round. A question that depends on another question still open in this round belongs to a *later* round, not this one.

Count rounds, not questions. A clear feature may need one round of three questions — that is a success, not a shortcut.

Put each round to the user with the **`AskUserQuestion` tool** when the harness has it:

- One tool question per frontier question, with a short `header` and 2–4 options phrased as *answers* (not yes/no), so there's no ambiguity about what agreeing means.
- Put your recommended option **first** and suffix its label with `(Recommended)`; use the option `description` for the one-line reason.
- The tool takes at most 4 questions per call. A frontier larger than that is still one round — send it as consecutive calls before recomputing.
- A question with no natural option set (open-ended "what should X contain?") goes in plain text alongside the call — the tool's automatic "Other" is not a substitute for a real open question.

Without the tool (e.g. a Codex session), ask the round as a numbered list with your recommendation on its own line under each question, so the user can reply by number ("1 A, 2 yes, 3 no — because…").

**Facts are yours; decisions are the user's.** When a frontier question needs a fact the environment can answer — code, config, git history, live read-only state — look it up; never ask the user. For anything beyond a quick read, dispatch an `Explore` sub-agent in the background. Don't block on it: a running lookup is an unsettled prerequisite, so only the questions downstream of it wait — ask the rest of the frontier now.

Decisions are the user's: put each one to them and wait. Never answer your own decision question and carry on. This matters most when reached from `/start`: a captured task summary states intent, it does not settle design decisions it didn't explicitly make.

**Some questions talking can't settle.** "How should this feel?", "Is this fast enough?", "Will the controller actually behave the way its docs say?" — these need something to react to or measure, not another rephrasing. When you hit one, stop asking it. Record it under `## Risks / open questions` with what would settle it, and propose a **spike as the plan's first phase** so the answer lands before the work that depends on it. Branches hanging off that question stay open; design only what doesn't depend on it.

**Reopen, don't paper over.** The frontier is your judgement, not a computed graph. Sometimes an answer changes a decision already settled, or two questions you put in the same round turn out to interact. When that happens, name the earlier decision it affects and reopen that branch — and everything downstream of it — in the next round. Don't quietly reconcile the conflict yourself.

## Closing gate

The dialogue is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed.

Before `/new-plan`, play the design back in one short message:

- **Decided** — each decision the user made, one line each.
- **Assumed** — anything you are taking as given that the user never explicitly decided: defaults you picked, facts you looked up that the design rests on, scope you inferred. This list is the point of the gate.
- **Deferred** — what goes to `## Risks / open questions`.

Then ask the user to confirm you share the same understanding. Do not scaffold the plan until they do. A correction reopens the affected branch as a new round.

## Output: fold the design into the plan

Once the closing gate passes, the terminal step is **`/new-plan <name>`**, then write the approved design into the scaffolded sections of `projects/<active>/plans/<name>.md`:

- **`## Goal`** ← the clarified purpose (one or two sentences). When reached from `/start`, this clarified Goal is also what `/start` pushes back to the task as the refined summary — so keep it clean and self-contained.
- **`## Success criteria`** ← the checkable conditions derived *with* the user during clarification. This is the Task Contract — brainstorming is what makes these collaboratively-derived rather than orchestrator-guessed.
- **`## Design`** ← the chosen approach, plus a one-line note on each alternative considered and why it lost. A lightweight decision record, so the "why" survives.
- **`## Risks / open questions`** ← anything surfaced but deferred during the design pass.

Leave **`## Phases`** for `/new-plan`'s normal job (decomposition into phases and `todo.md` items) — that's the writing-plans step, downstream of here.

Do **not** create a spec document in the **target repo**, and do not commit anything there. The brainstorm's own output is the **plan file** — `## Goal`, `## Success criteria`, `## Design`, `## Risks` — never a sibling design doc. The plan lives in the memory tree, like every other plan.

An **investigation** (`projects/<project>/investigations/<slug>.md`) is a different artifact: findings written while exploring, *before* the task existed. It is this skill's **input** — `/start` hands it over as the seed — never its output. It exists only when an investigation was actually done and its findings exceed the task summary's 500-char cap. This skill never writes one.

## Principles

- **YAGNI ruthlessly** — cut features that aren't needed from every design.
- **Explore alternatives** — always 2-3 approaches before settling.
- **Incremental validation** — present in sections, approve as you go.
- **Be flexible** — when an answer unsettles an earlier decision, reopen that branch rather than working around it.
- **Don't over-ask** — the goal is a good-enough design fast, not an interrogation. A short design for a clear feature is a success, not a shortcut.

## What this skill deliberately does not do

- It does not fire on every task — only Tier-3 features with open design questions.
- It does not run for the executor. Brainstorming is an orchestrator-role activity; whichever harness runs the main session owns it. Executors never brainstorm.
- It does not write code or invoke any implementation skill. Its only handoff is `/new-plan`.
- It does not own the task-provider bookkeeping. When reached from `/start`, linking the `task_ref`, pushing the summary, and flipping status are `/start`'s job — this skill only produces the design.
- It does not produce a spec file — not in the target repo, and not as a sibling of the plan. The design lives in the plan. (An `investigations/<slug>.md` may exist as this skill's *input*; the skill never writes one.)

<!-- partial:self-rating START (managed by scripts/apply-partial.sh — edit scripts/partials/self-rating.md) -->
## Self-rating (first-party)

This skill participates in the self-rating loop. The rating is a signal about
**this skill's own friction** — where its instructions were unclear, slow, or
made you guess — not about the correctness of the work product (that is the
Validator's job).

**Do not rate automatically.** Append a rating **only when the user asks** for

From seyio91/ai-memory-system, MIT.

More from seyio91/ai-memory-system