---
name: brainstorm
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
---

# Brainstorming Ideas Into Designs

Audience: AI coding agents first.

Turn ideas into fully formed designs through dialogue. When enough context, write spec and proceed — no approval gates.

Route check first: user wants an autonomous run from a one-line request (no authored spec/plan) → `factory` skill instead. Brainstorm is the AUTHORED-doc route: it ends by handing that doc to the same factory.

## Checklist

Create task per item, complete in order:

1. **Explore project context** — check files, docs, recent commits
2. **Ask clarifying questions** — one at a time until purpose/constraints/success criteria clear
3. **Propose viable approaches only (1-3)** — omit hacks/quick-fixes; trade-off table per approach; state recommended with reasoning; proceed unless user objects
4. **Write design doc** — auto when enough context; choose `PLAN_SLUG` (kebab key, reused by every artifact); save to `docs/specs/YYYY-MM-DD-<PLAN_SLUG>-design.md`
5. **Spec self-review** — Phase 1: completeness (placeholders, consistency, scope, ambiguity); Phase 2: architecture depth (deletion test, seam audit, depth scoring)
6. **Advisor review** — call advisor(); present questions to user if any; fix improvements/blockers silently
7. **Invoke plan skill** — auto after advisor approves; it writes `docs/plans/YYYY-MM-DD-<PLAN_SLUG>.md`
8. **Launch the factory** against that doc. From the repo root:
   ```bash
   cd <repoRoot> && factory adw_plan_build_test_quality docs/plans/YYYY-MM-DD-<PLAN_SLUG>.md
   ```
   A path argument resolves to that file's contents (`adw_modules/utils.py` `resolve_prompt`), so the authored doc IS the request. Fall back to the spec path when no plan doc exists. The run is autonomous; it streams to the `/factory` page — tell the user that is where they watch it.

## Process Flow

```dot
digraph brainstorm {
    "Explore project context" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Enough context?" [shape=diamond];
    "Propose 2-3 approaches (state recommendation, proceed)" [shape=box];
    "Write design doc" [shape=box];
    "Spec self-review (fix inline)" [shape=box];
    "Call advisor()" [shape=box];
    "Advisor has questions for user?" [shape=diamond];
    "Present questions to user, update spec" [shape=box];
    "Fix improvements/blockers silently" [shape=box];
    "Invoke plan skill" [shape=box];
    "Launch the factory against the plan doc" [shape=doublecircle];

    "Explore project context" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Enough context?";
    "Enough context?" -> "Ask clarifying questions" [label="no"];
    "Enough context?" -> "Propose 2-3 approaches (state recommendation, proceed)" [label="yes"];
    "Propose 2-3 approaches (state recommendation, proceed)" -> "Write design doc";
    "Write design doc" -> "Spec self-review (fix inline)";
    "Spec self-review (fix inline)" -> "Call advisor()";
    "Call advisor()" -> "Advisor has questions for user?";
    "Advisor has questions for user?" -> "Present questions to user, update spec" [label="yes"];
    "Present questions to user, update spec" -> "Call advisor()";
    "Advisor has questions for user?" -> "Fix improvements/blockers silently" [label="no"];
    "Fix improvements/blockers silently" -> "Invoke plan skill";
}
```

**Terminal state: invoke plan, then launch the factory.** After advisor approval → invoke plan immediately. After plan saves its doc → launch the factory against it (step 8) and point the user at `/factory`. Do NOT invoke frontend-design, mcp-builder, or any other implementation skill.

## Understanding the Idea

- Check project state first (files, docs, recent commits)
- Assess scope before detailed questions: multiple independent subsystems → flag and decompose first
- Too large for one spec → decompose into sub-projects, brainstorm first sub-project. Each gets own spec → plan → implementation cycle
- Use `AskUserQuestion` for ALL clarifying questions — one per call, always include options. Focus on: purpose, constraints, success criteria

## Exploring Approaches

Only present approaches worth building. Omit hacks, quick fixes, clearly inferior options. Don't pad to reach a count.

Per approach, evaluate:
- **Robustness** — handles failures, edge cases, unexpected load?
- **Long-term maintainability** — easy to change/extend/reason about in 2 years?
- **Scalability** — holds under 10x data/users?
- **Performance** — latency, throughput, resource usage?
- **Reversibility** — one-way door (schema migration, protocol change, vendor lock-in) or two-way door? Prefer reversible when uncertain. One-way doors require stronger justification.
- **SEO/GEO** — crawlability, structured data, rendering strategy? *(skip if not web-facing)*
- **Infra cost** — compute, storage, egress, vendor lock-in? *(skip if negligible)*

Format per approach:
```
### Approach N: [Name]
[One-line description]

| Dimension | Assessment |
|-----------|------------|
| Robustness | ... |
| Long-term | ... |
| Scalability | ... |
| Performance | ... |
| Reversibility | two-way door / one-way door — [what locks you in or frees you] |
| Infra cost | ... |  ← only if relevant

**Weakness:** [one honest trade-off]
```

End with:
```
**Recommended: Approach N** — [2-3 sentences why it wins on dimensions that matter most]
```

Proceed with recommended unless user objects. YAGNI: no approach includes unneeded scope.

## Writing the Spec

- When enough context → write spec. Do not ask permission.
- **Choose `PLAN_SLUG` now** — short kebab-case key derived from the topic (e.g. `auth-rework`). It is the primary key for every artifact this run. One slug, reused verbatim across spec and plan. Pass it to the plan skill so the plan doc shares the stem.
- Save spec to `docs/specs/YYYY-MM-DD-<PLAN_SLUG>-design.md`
- Cover: architecture, components, data flow, error handling, testing
- Scale sections to complexity
- Units: one clear purpose, well-defined interfaces, independently testable — can someone understand a unit without reading its internals? Can internals change without breaking consumers? If not, boundaries need work.
- In existing codebases: explore structure first, follow patterns. Include targeted improvements where existing code has problems affecting this work. No unrelated refactoring.

### Contract-level spec, NOT a code dump

**A spec pins DECISIONS and SEAMS in prose; it NEVER pastes implementation bodies.** Highest-altitude doc in the chain — leans MORE to prose than the plan does. The implementer writes the body for free by reading the repo; a body written into the spec is paid-for work the plan re-states, the implementer re-derives, and advisor + code-reviewer re-read — quadruple cost plus context rot. Same body-bloat economics `[[plan]]` applies per task, applied here at design level.

Pin in prose: architecture, component responsibilities, data flow, error-handling strategy, test strategy — and each **seam**: interface signature, type / data shape, route / schema, required literal string.

**PERMIT (keep — seams + design, not bodies):**
- interface / type signatures, function shapes (the contract, not the logic)
- data shapes, schema / route / IO shapes, JSON examples
- a required literal string / format, verbatim
- diagrams (dot / mermaid / ascii)
- illustrative snippet for a non-obvious algorithm core / tricky seam — keep ONLY the shape callers must match, any length; never the surrounding body

**NEVER paste:**
- full component / function / class body — describe behavior in bullets + pin its signature
- full stylesheet, full markup block, full config file — name the tokens / structure, link the pattern file
- any fenced block whose lines are implementation logic the implementer re-derives for free

**NEVER write the spec as a before/after code diff of the existing file.** Modifying existing code → describe the change as a CONTRACT (what the seam becomes + behavior delta), NOT a patch. Section headings like `## CSS changes`, `## HTML changes`, `## JS changes`, or `Current: <code> / Required: <code>` pairs are the tell — they pull the whole file in as a diff and balloon the spec. Instead: name the file + the responsibility that changes, pin the new seam, state the behavior delta in prose. The implementer produces the actual diff by reading the repo.

Decide BEFORE you type each fenced block: would it show HOW it works (a body)? Emit the signature + behavior prose instead — never type the body. Would it show the SHAPE callers must match (a seam)? Emit it. Classify at the keystroke; a body costs zero tokens because it is never drafted.

**Emit seams from the FIRST keystroke — do NOT draft a body then strip it.** As you write each component, reach for the signature + behavior bullets, never the implementation. Drafting full code then deleting it still burns the tokens and rots context; the win is in never writing it.

Before/after — same component:

```ts
// DO NOT — full body pasted into spec (implementer re-derives this for free):
function PreviewPane({ theme }: Props) {
  const [scale, setScale] = useState(1);
  useEffect(() => { /* 40 more lines of resize logic */ }, []);
  return <div style={{ /* 30 lines of inline style */ }}>…</div>;
}
```

```
// DO — seam + behavior:
PreviewPane({ theme: ThemeTokens }): JSX
  - renders live preview of `theme`; debounced 150ms on token change
  - fits parent via ResizeObserver; min-scale 0.5
  - styling: design tokens only (var(--*)), no inline literals — see src/components/Pane.tsx pattern
```

## Spec Self-Review

Two phases. Run both before calling advisor.

### Phase 1: Completeness

1. **Placeholder scan:** "TBD", "TODO", incomplete sections, vague requirements? Fix them.
2. **Internal consistency:** Sections contradict each other? Architecture match features?
3. **Scope check:** Focused enough for one plan, or needs decomposition?
4. **Ambiguity check:** Requirement interpretable two ways? Pick one, make it explicit.

Fix inline. (No body-bloat scan here — bodies are prevented at generation time by "Contract-level spec, NOT a code dump"; there is nothing to strip after the fact.)

### Phase 2: Architecture Depth

**Size gate:** fewer than 3 distinct proposed modules → skip (trivial spec).

Per module, apply:

**Deletion test** — delete module entirely → complexity scatters to callers? Yes → earns its boundary. No → collapse into caller.

**Single-adapter test** — seam has exactly one plausible implementation? YAGNI: collapse until second adapter needed.

**Seam audit** — boundary hides non-trivial complexity behind stable interface, or purely organizational? Decorative seams → collapse. Classic failure: hexagonal/ports-adapters/CQRS on a service whose primary function is data movement.

**Depth score per module:**
- *Shallow:* interface mirrors internal representation. No hiding.
- *Medium:* hides some implementation detail; interface survives one refactor.
- *Deep:* callers can't tell how it works; internals replaceable entirely.

Spec should have mostly medium/deep. All-shallow = over-decomposed.

**Revision candidates:** flagged modules (failed deletion, single-adapter, decorative, all-shallow). Present collapse/merge via `AskUserQuestion`. Update for accepted. For rejections, record reason.

**Append to spec:** `## Architecture Decisions` section — accepted collapses + rejected candidates with one-line reason each.

## Advisor Review Gate

After self-review, call advisor():

- **Advisor has questions** → present to user, update spec, call advisor() again
- **Advisor has only improvements/blockers** → fix inline, no user involvement
- **Spec passes** → invoke plan immediately, no user confirmation

**Only escalate to user when advisor has genuine questions that can't be resolved from context. Everything else: fix silently and proceed.**

## Keeping intent alive (long runs)

A long run WILL compact and lose goal, intent and standing instructions. The spec and the plan doc are the durable record — they live in the repo and survive any compaction. Point at them, do not duplicate them.

Event-anchored, NOT timed (agents have no timer). After a compaction system-reminder, **native Read** the spec back into context. MUST be native Read — an exec call defeats the purpose by keeping bytes out of the thread.

Found drift? Correct the spec, then re-read it, so what re-enters context is current rather than stale.

**Surface the doc path to the user.** They re-launch by pointing the factory at it, and cannot if they never learned where it is:

> Saved `docs/plans/2026-08-08-auth-rework.md` — re-launch anytime with `factory adw_plan_build_test_quality docs/plans/2026-08-08-auth-rework.md`, and watch it on `/factory`.

### End-of-session report

Brief: what was done, what's blocked, what's deferred, what's canceled. **No "next action to do"** — if a next action is known, do it, don't announce it.

### Escalate to user only for real decisions

Before any `AskUserQuestion`: is this genuinely the user's call (irreversible, preference-bound, or outside your authority), or can advisor() or a sensible default resolve it? Prefer advisor / default. Fire `gated` + `AskUserQuestion` only for a true user decision.

## Visual Mockups

Invoke `creating-mockups` only when the user's request contains either exact phrase: `You should create mockups` or `make html mockups`. Exact means case-sensitive and word-for-word. For every other request—including UI wireframes, layout comparisons, visual design choices, synonyms, or implied interest—do not invoke `creating-mockups` and do not create mockups.

## Key Principles

- Use `AskUserQuestion` for ALL questions — NEVER plain text
- One question per call
- YAGNI ruthlessly
- Auto-proceed when ready — no permission needed to write spec or invoke plan
- Approaches: only viable options, always recommend one, always explain why