feather-brainstorm

name

feather-brainstorm

description

Horizon-expansion and structured capture skill. **TRIGGER when the user expresses intent to build, design, or shape a new feature, app, or project** — phrases like "I want to build X", "let's design Y", "thinking about a tool that does Z", "want to brainstorm", or any opening that describes a future feature/app rather than asking to fix or modify existing code. **MUST trigger BEFORE any scaffolding, file creation, or tech-stack discussion** — the brainstorm captures intent before code. Do not ask about frameworks, auth libraries, or deployment in this phase; those belong in feather-spec's design.md. Produces docs/brainstorm.md — a project-level discovery doc capturing workflow, pain points, and decomposition into features. For visual layout decisions, generates HTML mockups in the user's browser. Output feeds into feather-spec, which then specs each feature one at a time. Part of the feather-flow pipeline.

Feather Brainstorm

Expand horizons before narrowing to spec. The output is a document, not a transcript — a coherent record of what's being built and why, that a reader six months later can understand without the chat log.

Voice and Substance Discipline

Substance-tier rule: quote the user verbatim when the framing is the substance — workflows, jobs-to-be-done, what they're trying to accomplish, the meaty challenges, and any term the user uses deliberately (their domain language). For everything else — yes/no confirmations, picking from offered options, light restatements — fold into agent prose.

When to quote verbatim

• A workflow description in the user's own framing
• A job to be done, an objective, a constraint, the why
• Domain language — the user's terms for their work, which the spec must preserve
• Pushback or reframing where the disagreement is the data
• A decision with its reasoning, when the reasoning is the user's own

When to fold into prose

• Confirmations (yes / agreed / sounds good / ok)
• Picking from a list the agent offered — record the choice, not the assent
• Restating the same thing in different words
• Anywhere the substance was the agent's framing and the user just confirmed

Light cleanup vs reframing (when you do quote)

Allowed (light cleanup)	Not allowed (reframing)
Fix a typo ("recieve" → "receive")	Change the user's word for a more precise one
Remove a false start ("I mean — actually what I want is X")	Summarise a long statement into a shorter one
Remove filler ("uh", "like", "you know")	Resolve a vague statement into something concrete
Fix punctuation	Combine two statements into one

The verbatim test: Would the user recognise this as their own words? If not, it is reframing.

Handling contradictions

When a user contradicts themselves, do not silently resolve it.

Procedure:

1. Quote both statements verbatim
2. Name the tension without editorialising
3. Ask the user to resolve in their own words

Format:

"You said two things that pull in different directions:

Earlier: '' Later: ''

Which reflects what you actually want, or is it somewhere in between?"

Record the resolution verbatim. Keep both original quotes in brainstorm.md with a note: "User resolved: second statement supersedes first." Never delete the original — the contradiction and its resolution are part of the discussion log.

---

Broadening Stance (load-bearing rule)

Brainstorm's stance is broadening. Even when the user gives a clear, specific input ("I want a todo app for my team"), surface 1–2 horizon-expanding alternatives before accepting and moving on. The user may have committed to a framing without realizing other framings exist; the skill's job is to make the design space visible before it gets narrowed.

This is the explore-mode virtue borrowed from OpenSpec: a clear statement is a starting point for exploration, not an ending point. Horizons-expanded discovery beats horizons-confirmed discovery for catching wrong assumptions early.

How to apply:

• On vague inputs → Phase 0 shape & scope check already broadens (3–4 shape options). Standard flow.
• On specific inputs ("a Kanban board for engineering tasks") → still surface 1–2 alternatives the user may not have considered ("Considered: a flat list with priority tags? a calendar view?"). Frame as questions, not as objections — the user still chooses.
• On pivot inputs → broaden the what changed before narrowing to the new direction.

The test: would the user, six months later reading the brainstorm doc, see "we considered X, Y, Z and chose Y because..." and feel that the choice was informed? If yes, broadening worked. If they only see "we built Y" with no record of the alternatives, broadening failed.

The output of broadening at the project level lives across the relevant sections of docs/brainstorm.md (Today's workflow / Pain points / Features / How features connect) — alternatives considered show up as inline notes within those sections when the user picked one path over another. Per-feature alternatives that emerge during spec authoring belong in that feature's own spec.md. Spec records the commitment; brainstorm records the project-level path that led there.

Bounding is spec's job, not brainstorm's. Resist the temptation to bound during discovery. If the user picks an alternative mid-conversation, record the choice with reasoning — don't translate it into a committed rule until feather-spec authors spec.md.

---

Entry Points

Entry point	Signal	Opening move
Vague	"I want a todo app", pain point without shape	Phase 0 → discovery phase
Specific	Clear feature with known screens/actions	Phase 0 → skip discovery, go to horizon expansion
Pivot	Mid-implementation, scope changed	Phase 0 → capture what changed and why first, then expand
Multi-feature	User describes 2+ features ("projects, tasks, comments, notifications")	Phase 0 → scope detection writes ROADMAP.md and captures all features in project-level brainstorm.md; user picks which to spec first

Cadence: honour the mode the user picked in Phase 0b mode negotiation.

• In walk-through mode: one open question at a time, listen fully before asking the next.
• In assumption mode: batch — propose a starting picture, ask for ✅/✏️/❌ across many items at once.
• In paste-driven mode: process input quietly, ask only about gaps.

If the entry point is ambiguous, ask one clarifying question to route to the right mode. Then let mode negotiation handle the rest (Concierge Default — explain the modes upfront so the user can self-select).

---

Phase 0 — Pre-Discovery

Before discovery or horizon expansion, surface scope: are we building one capability or several? Default to silent detection then explicit confirmation (Concierge Default — friendly reframing wins over making the user self-classify).

Shape and scope check

Always engage scope before mode, but do so in plain language and as a broadening move — reflect what you heard, then offer 2–4 concrete shapes the system could take, and let the user react. This serves two jobs in one turn: confirms what we're shaping, and opens the design space before narrowing.

Do NOT say "capability" to the user — that's our internal routing vocabulary (used in this skill, in feather-spec, in ROADMAP.md). To the user, talk about "shape", "kind of system", or just the thing they named ("project management tool", "note-taking app", etc.).

Standard format (single-shape input):

"Reflecting back what I heard: <one-sentence plain reframe of the request, no jargon>.

'' can mean a few different things and the shape changes everything else. Three rough shapes I see this could land in:

1. —
2. —
3. —

Type 1, 2, or 3 — or describe it in your own words if none fit."

Number the options. Typing "1" is the lowest-friction reply for a non-technical user; spelling out the shape name or having to describe it from scratch is more cognitive load. Concierge Default.

Do NOT include an escape hatch like "if you'd rather walk through how you work today." The mode menu (next turn) explicitly offers walk-through as one of three modes. Mentioning it here pre-announces the next gate and creates duplicate paths the user has to mentally deconflict. Trust the next gate to handle it.

STOP. End your turn here. Do NOT show the mode menu in the same turn. Wait for the user's reply on shape before continuing.

Generating the shape options

Three to four concrete shapes, drawn from the input. Aim for shapes that genuinely differ in what they imply — data model, permission model, who's the audience, what "done" means. Don't list near-duplicates.

Example shape sets by domain:

• "Project management tool" → Team-shared workspace · Personal-with-team-visibility · Issue-tracker style · Client-facing tracker
• "Note-taking app" → Personal commonplace book · Team knowledge base · Public publishing platform · Linked thinking workspace
• "Shopping list" → Single-user list · Shared household list · Meal-plan-driven list
• "Customer database" → Lightweight CRM · Sales pipeline tracker · Support ticket system · Marketing list

Why this works (vs old "Reading this as one capability"): The old prompt asked the user to validate an internal classification ("is this one capability?"). The new prompt asks the user to pick from shapes they can recognise. Concierge Default — non-technical users react to options better than they generate from scratch.

Relationship to discovery

The shape probe is higher-level than discovery and does not replace it. Shape = "what kind of system is this conceptually." Discovery = "how does work happen today specifically." Discovery still happens in Phase 1 (walk-through mode, explicit) or implicitly in Phase 2 (assumption mode, baked into the proposed picture). The shape probe just informs which proposal to make or which workflow questions to start with.

When the user's opening message names multiple distinct things — each big enough to be planned and shipped on its own — list them back in plain words and confirm:

"What you're describing sounds like several separate things rather than one — each big enough to plan and build on its own:

• —
• —
• —

I'll record each one so none gets lost. Then we'll go deep on one first — which feels most important to start with? (Or tell me if I'm splitting things that should really be one thing.)"

(Internally, each becomes a row in docs/ROADMAP.md. The user doesn't need to see the word "capability" or the file path unless they ask.)

Cues that suggest multiple capabilities:

• Comma-separated list of nouns each with their own verbs ("projects, tasks, comments, notifications")
• Sentence structure that pairs each noun with a distinct user action
• The user says "system" or "platform" rather than "feature" or "screen"

Cues that suggest one capability with multiple entities:

• One verb across multiple nouns ("manage projects and tasks")
• Tightly coupled lifecycle ("a project that contains tasks")
• The user uses "and" between two things that share screens

If unsure, ask explicitly:

"Is this one capability that touches multiple things, or several capabilities that should be planned separately?"

Writing ROADMAP.md

When scope detection identifies N features (N ≥ 1), write or update docs/ROADMAP.md. The roadmap is the inventory + status of all features in the project. The project-level docs/brainstorm.md (written in Phase 3) carries the narrative of why these features exist and how they fit together; ROADMAP.md is the lightweight tracker.

If ROADMAP.md does not exist, create it. If it exists, append new entries — do not rewrite existing rows.

# Roadmap

| Status | Name | Description | Depends on | Notes |
|---|---|---|---|---|
| 🔨 active | <feature-name> | <one-line description> | — | brainstormed YYYY-MM-DD |
| ⏸ planned | <feature-name> | <one-line description> | <other or —> | not yet specced |

Status values:

• 🔨 active — currently being specced or built
• ⏸ planned — known about, not yet started
• ✅ done — shipped (PR merged)
• ❄ frozen — deliberately deprioritized; keep entry to record the decision

Project-level discovery captures all features at once. Unlike the old per-feature brainstorm model, the project-level docs/brainstorm.md written in Phase 3 captures all identified features in its ## Features section — workflow capture is a cross-feature activity by design. The feather-spec phase then handles each feature one at a time, producing per-feature spec.md files. The feature you select to spec first gets 🔨 active in ROADMAP.md; the others stay ⏸ planned until specced.

Mode negotiation

Show the mode menu in its own turn, only AFTER the user has confirmed or corrected scope in a previous turn. Never bundle the mode menu with the scope confirmation question.

Always show the user the mode menu. This step is non-skippable, even when:

• The session is in auto mode / "minimize interruptions" mode
• The user gave a substantive opening prompt suggesting they know what they want
• The agent thinks it can guess the right mode from context
• The conversation is already going fast and the menu feels like friction

Mode is a shaping decision — it determines the entire interaction style for the session (how questions are batched, whether discovery happens, where input comes from). Routine decisions (small defaults, obvious choices) can be made silently. Shaping decisions cannot. Auto mode means don't ask on routine decisions; it does not mean skip Concierge Default UX moments.

If the agent is in auto mode and feels pressure to be efficient, the menu itself is the efficient move — it lets the user pick their pace in one turn, versus the agent guessing wrong and the user having to redirect.

Use this structured menu with descriptions (Concierge Default — handhold the user who doesn't yet know how this skill works):

"Three ways we can take this forward. Each fits a different starting state — pick what matches yours:

#	Mode	When it fits	What I do	What you do
1	Walk through your current workflow	You already work this way (formally or ad hoc) and want the new system to fit your real workflow	Ask about today's process step-by-step, extract screens and pain points	Describe how it works now, what breaks
2	Let AI propose something	You don't have a clear picture yet and would rather react to a proposal than answer questions from scratch	Propose a starting picture (entities, screens, defaults); flag tradeoffs	Mark ✅ keep / ✏️ change / ❌ drop per item, and iterate
3	I have a clear idea	You have notes, a PRD, a Slack thread, or a draft spec	Extract structure from what you gave me; ask only about gaps	Paste the source material

Type 1, 2, or 3 — modes aren't locked, you can switch anytime by saying 'let AI propose' or 'let me paste something'."

Honour the picked mode for the rest of the session. If the user switches mid-session, the agent adapts without re-asking.

Routing: mode determines which Phase 1 path to take:

• Walk-through → Phase 1 Discovery (full)
• Assumption → skip discovery, go straight to Phase 2 with proposed assumptions (see Assumption-mode output template below)
• Paste-driven → ingest the source, derive Phase 2 scaffolding from it, ask about gaps

Assumption-mode output template

Even in assumption mode, Phase 2.1 (restate in user's terms) still gates the picture — open with one sentence pulled from what the user said, then dive in. Phase 2.3 (visual offer) still fires after the screens land — offer ASCII / HTML / skip.

The picture mirrors the brainstorm.md sections in this order:

1. Restatement — one sentence in user's words ("So what you're describing is: …").
2. What this project is — one paragraph, plain language.
3. Who uses it — actors across the whole system. One bullet per role.
4. Today's workflow — the cross-feature flow (a proposed picture in assumption mode; user corrects).
5. Pain points — the friction motivating the project, traceable to today's workflow.
6. Features — the decomposition. One bullet per feature with a one-line role.
7. How features connect — integration points between features.
8. App shell — sidebar / top bar / command palette / toasts / modals / page layout (the chrome each feature renders inside; feeds the project mockup in Phase 2.5).
9. Open questions — net-new project-level questions only. Feature-level questions belong in each feature's spec.md later, not here.

Numbering rule. Every markable item — entity, screen, default, out-of-scope item, open question — gets a single running counter (1, 2, 3, …) so the user can reference items by number across the whole picture.

Atomicity rule. One decision per numbered line. Compound bullets ("open first, then done, sorted by date") split into separate numbered items so the user can ✏️ or ❌ each independently.

One-screen rule (binding constraint). Each turn presents at most one viewport-worth of content — what fits without the user scrolling on a normal-sized chat window. Practical budget: ~25 lines of rendered markdown, including headers, spacing, and the closing marking instruction. This is stricter than item counts and dominates them when they conflict.

Per-section cap (Miller's 7±2). Within the screen-worth, each section caps at 7 numbered items. If a section exceeds 7, that's a granularity signal — items either roll up into a parent decision, or push down to design.md. Splitting visually past 7 doesn't fix the underlying detail-leak.

Chunking when the full picture exceeds one screen. Present sections in sequence — who uses it + today's workflow → user replies → pain points → user replies → features + how they connect → user replies → open questions. Each turn = one screen. Numbering continues across turns. The user reacts to one chunk at a time without losing the overall thread.

Sequential confirmation kicks in only when the picture genuinely exceeds one screen even after detail-stripping (tech-name rule, entity-detail rule, tightened out-of-scope all applied). If everything fits, present it as one output with section headers as natural visual breaks.

Marking instruction (phrase-based reply — numbers refer to items only). Close the picture (or each chunk) with explicit phrases the user can type. Numbers in this skill always refer to item numbers in the picture — they are never reused to mean response modes. Response modes are signaled by short phrases the agent suggests:

"Three ways to reply:

• 'all ok' (or 'yes to all', 'looks good') — keep the picture as-is, move on
• List items to change in plain words — e.g., '5 should be only-assignee, 7 drop, rest fine'
• 'show alternatives for #N' — see other options for a specific item (e.g., 'show alternatives for #5')"

Never use emoji (✅ ✏️ ❌) as input syntax the user must type back. Many users are on keyboards or terminals where emoji entry is awkward; phrase-based replies + item numbers are universal. Emoji are fine in your output (for visual scanning); they are not fine as a required reply format.

Always include an explicit "yes to all" phrase in the suggestions ('all ok', 'yes to all', 'looks good'). Implicit "silence means keep" is invisible to the user; the most common reply deserves a discoverable, named path.

Number discipline. Numbers in feather-brainstorm have one meaning at a time, and within the assumption-mode picture that meaning is item references. Do not introduce a second numbered scheme (1 / 2 / 3 for response modes) that overlaps with item numbering — the user will conflate them.

Tech-name rule. Brainstorm output never names a framework, library, auth provider, database, or hosting platform. Say what the user does ("email sign-in", "drag-and-drop upload"); defer the tech to design.md. ("Convex Auth, already scaffolded" → "email sign-in".)

Entity-detail rule. Entities in brainstorm are one-line "what this represents" descriptions only — no field schemas, no types, no foreign-key notes. Fields belong in design.md.

Inline parentheticals for alternatives. Surface alternatives as inline parentheticals on the relevant bullet ("5. Anyone can mark a task done. (Alternative: only the assignee can mark done.)"), per Phase 2.4 Format A. The agent does not need to suppress callout-style decorations applied by Claude Code's active output style — those are harness-rendered, not agent-chosen.

---

Phase 1 — Discovery (optional, skip if specific or pivot)

Primary question — ask this first and listen fully before asking anything else:

"Walk me through how you do this today, step by step."

Let the user describe their current workflow completely. Do not interrupt. After they finish, extract:

What you heard	What it reveals
Steps in sequence	Screens and actions needed
Handoffs between people or tools	Integration points
Delays or waiting	Automation opportunities
Workarounds	Pain points to solve
Repetition	Template or default candidates

Follow-up questions — use only what's needed:

• "What are you trying to accomplish?" → underlying goal
• "What makes this frustrating?" → pain points and priority
• "What would success look like?" → acceptance criteria in user's words
• "Where does this break down?" → edge cases and failure modes
• "What do you wish happened automatically?" → automation opportunities

Record the workflow exactly as the user described it. Number the steps. Do not reframe. Do not summarise away specifics.

---

Phase 1b — Paste-driven ingestion (skip if not in mode 3)

Mode 3's whole point: the user has already done the discovery work in some form (a PRD, a Slack thread, draft notes, an old design doc). The agent's job is to read the source completely first, then surface only what's missing — not to interrogate the user for things the source already answers.

If the user is in mode 1 (walk-through) or mode 2 (assumption), skip this section entirely and proceed to Phase 2.

1b.1 The read-pass discipline

When the user pastes source material, do NOT respond with questions yet. Read the entire source first and silently extract:

Extract	Look for
Actors / users	Named roles, personas, pronouns ("our team", "the designers", specific names)
The why / pain	Statements about current frustration, broken workflows, what's missing today
Screens / surfaces implied	Phrases like "a view that...", "a page where...", named screens
Behaviors / rules	Statements with "should", "must", "always", "never"; status flows, sort orders, defaults
Out-of-scope items	Explicit "no X", "not for v1", "skip Y for now"
Open questions	Question marks the user themselves left, or "I'm not sure", "need to decide"
Tech notes	Framework names, library hints, hosting choices, auth providers — these go to each feature's design.md later, never into the project-level brainstorm

After the read-pass, hold a mental model of what the source covers. Only then move to gap detection.

1b.2 Gap detection

For each section the project-level brainstorm template requires (What this project is / Who uses it / Today's workflow / Pain points / Features / How features connect / Open questions), ask yourself:

1. Did the source answer this fully? → no follow-up needed
2. Did the source answer it partially? → narrow gap question
3. Did the source not address it? → broader gap question

The threshold for asking is high: re-asking something the source already answered breaks the trust mode 3 establishes ("I gave you this; don't make me repeat it"). When in doubt, prefer to surface the agent's interpretation for confirmation rather than asking the user to re-state.

1b.3 Formatting gap questions

One numbered turn covering only net-new questions. Example format:

"Got it, I've read through the PRD. A few things I couldn't find answers to:

1. — <specific question, plain language>
2. —
3. —

Reply by number, or just talk through them in your own words."

Cap gap questions at ~5. If you're tempted to ask more, the source probably had more structure than you extracted; re-read first.

1b.4 Handling source variants

Source shape	Approach
Highly specific PRD (most fields decided)	Extract liberally; gap-questions are mostly clarifying edge cases
Vague notes / Slack thread	Extract what you can; gap-questions cover the larger missing structure; consider whether mode 1 or 2 might serve better — offer to switch
Highly opinionated design doc	Extract the what and why; the how (tech, screens) belongs in spec or design, not in brainstorm — note for forward inheritance
Contradictory source	Surface contradictions verbatim per the Voice and Substance Discipline rules (top of skill); ask the user to resolve

1b.5 Verbatim preservation from the source

The source is the user's own words by definition — it's the primary source for the ## In the user's own words section. Pull product-substance quotes directly from the pasted material (workflow descriptions, jobs-to-be-done, the why, domain language). Apply the standard "do NOT include" filter (no implementation tangents, process direction, or agent-meta — see Phase 3 capture rules).

If a quote needs minor cleanup for standalone readability, the standard light-cleanup rules apply: typos, false starts, filler. Inserting a clarifier in [brackets] is permitted when essential for the quote to read on its own without the surrounding source context.

1b.6 Forward to Phase 2

After gap questions are resolved, the agent has a complete picture: source-extracted content + gap-resolved content. Skip directly to Phase 2.5 (surface alternatives considered) or Phase 2.6 (scope boundary) as needed. The Phase 2 horizon expansion runs lighter in mode 3 because much of the broadening is implicit in the source — but the Broadening Stance still applies: surface 1–2 alternatives even on a clear PRD if the source committed to a framing without acknowledging others.

1b.7 Prototype in mode 3

Same as other modes: Phase 2.5 (Build the prototype) still fires after data model and app shell are sketched. Mode 3 is no exception — a paste-driven brainstorm benefits from docs/sample-data.json + docs/mockup.html to validate that the parsed PRD actually feels right when rendered. If the PRD names specific layouts, honor them directly inside the project mockup.

---

Phase 2 — Horizon Expansion

2.1 Restate in user's terms

One sentence, pulled from what the user said:

"So what you're describing is: [user's words]."

Confirm before moving on. If wrong, correct and restart.

2.2 Identify feature shape (internal routing only)

Each feature has one of three internal shapes. The shape is internal routing information that feather-spec uses; it does not appear in user-facing brainstorm content.

Shape (internal name)	What it means
Standard	self-contained feature owning one or two closely-related entities
Aggregation	feature that pulls from multiple existing features rather than owning its own data
Cross-feature	small feature that connects two existing features without owning data of its own

The shape stays internal — it does not appear in docs/brainstorm.md. If the user asks about routing taxonomy explicitly, surface it then ("internally feather-spec routes this as a Standard feature"); otherwise stay in plain language (Concierge Default).

2.3 Surface screens (per feature)

When discovery surfaces screens for a specific feature, list them with name + one-line purpose.

Screen 1: Upload — user submits an xlsx file
Screen 2: Dataset List — user browses what they've imported

Ask: "Does this match what you're picturing, or are there screens missing?"

Note on placement. Screens themselves do not appear inline in docs/brainstorm.md (the project-level doc captures workflow, pain points, the Features list, and the App shell — not per-screen detail). Screens fold inline into each feature's spec.md, written later by feather-spec. Layout validation happens at the project level via docs/mockup.html, generated in Phase 2.5 (Build the prototype).

2.4 Surface options and alternatives

For each non-obvious design decision, present options before recommending. The user sees the full space first. Two formats — pick per decision:

Format A — Assumption + alternative (best when there's a clear sensible default and one realistic alternative):

"Membership model — simplest assumption: one shared workspace, everyone signed in sees all projects. (Alternative: per-project member lists. Pick later if needed.)"

This is a single sentence with three parts: the assumption, the alternative in parentheses, and a "how to override" hint. Concierge Default — low-friction for power users, transparent to noobs. Use this format whenever a "sensible default" is genuinely sensible.

Format B — Options table (best when there are 2–3 genuinely distinct options worth comparing):

Decision: How should the upload confirm flow work?

Option A — Navigate to dataset list after success
  Pro: closes the import loop, user sees result in context
  Con: extra navigation to import again

Option B — Stay on upload screen with success message
  Pro: easy to import multiple files in sequence
  Con: user must navigate to see data

After presenting: "Which direction feels right?"

2.4.5 Visual Companion (deprecated — see Phase 2.5)

The per-screen, per-feature mockup HTML companion is gone. Layout validation now happens at the project level via one comprehensive prototype (docs/mockup.html) generated in Phase 2.5 — Build the prototype. Per-feature screens/<screen>-NN.html sidecars are no longer produced.

If a layout decision arises during brainstorming that's contested enough to need side-by-side comparison, surface the options in words (Format B options table from Phase 2.4) and let the user pick — the chosen layout then renders inside docs/mockup.html when Phase 2.5 fires.

2.5 Build the prototype

After the data model is sketched (Phase 2.3) and the app shell is discussed (which feeds the brainstorm.md ## App shell section), generate two concrete artifacts that let the user feel the system:

• docs/sample-data.json — realistic sample data for each entity, ~5–10 instances per entity, drawing on the user's domain language (their own names, their own project examples)
• docs/mockup.html — a self-contained HTML page implementing the app shell and rendering all screens, populated by sample-data.json

2.5.1 Build mode — concierge offer

Before generating the mockup, offer two build modes:

"I'll generate the app mockup at docs/mockup.html. Two build modes:

1 — Read-only (default) — sample data displays across all screens; navigation between screens works; clicks log to console but don't change state. Quick to build, catches "is this navigable / do screens look right / is sample data realistic" — most validation value at low cost. 2 — Fully interactive — sample data is mutable; click status pills to update; add/edit/delete via forms; export-to-JSON saves modified state. ~3–5× build time, much higher validation power.

Reply 1 or 2. Default is 1."

Honor the user's choice. If 1 (read-only), proceed without state-mutation logic. If 2, build a thin vanilla-JS state layer over sample-data.json and add an "Export JSON" button.

2.5.2 Sample data generation

Generate sample-data.json based on the data model from Phase 2.3 and the user's domain. Format:

{
  "<entity_name_plural>": [
    { "id": "<short_id>", "<field>": "<realistic_value>", ... },
    ...
  ],
  "<other_entity>": [
    ...
  ]
}

• Use the user's actual names where mentioned (Asha, Theo, Anya, Ben — not Jane Doe / John Smith)
• Use their actual project examples where mentioned ("Launch website", "Q2 marketing campaign" — not generic ones)
• Use ID prefixes that hint at entity (p_1 for projects, t_1 for tasks, tm_1 for team members)
• Keep dates realistic and recent (within the last 60 days)
• Cover edge cases lightly: at least one stale-task instance, one Done task, one Blocked task, etc., depending on the data model

After generating, surface the data to the user:

"Sample data generated at docs/sample-data.json — projects, tasks, team members. Skim it and tell me if anything's off — names, project examples, status mix. Reply 'all ok' to proceed to mockup, or call out specific items to change."

2.5.3 Mockup generation

Build docs/mockup.html as a single self-contained file:

• One <style> block with minimal CSS for the app shell + screen layouts
• One <script> block (with sample-data.json either inlined or fetched at load)
• HTML structure:
  • App shell (sidebar nav, top bar, optional command palette stub)
  • Main content area showing one screen at a time, switched by sidebar nav
  • All major screens implemented (one section per screen, in flow order)
• For mode 1 (read-only): screens render data; clicks log to console
• For mode 2 (interactive): clicks dispatch to a thin state-mutation layer; "Export JSON" button serializes current state

After generating, surface to the user:

"Mockup built at docs/mockup.html. Open it in your browser to play with the app. Tell me what feels right, what feels off, what's missing. The mockup will keep getting updated as we refine the brainstorm."

2.5.4 Mockup-update protocol

Whenever the brainstorm conversation surfaces a new entity, screen, behavior, or app-shell element AFTER the initial prototype is built, update the mockup alongside the doc:

• New entity → add to sample-data.json and to the data model section in brainstorm.md
• New screen → add to mockup HTML and to the relevant feature's screens index
• New behavior → if read-only mode, log to console with the behavior name; if interactive, implement the state mutation
• New shell element → update mockup HTML and the brainstorm.md ## App shell section

The mockup IS the running record of what's been validated. Don't let it diverge from brainstorm.md.

2.5.5 Optional: refresh sample data

If the user wants to re-roll sample data (e.g., "make these examples more like SaaS tools, less like creative agency work"), regenerate sample-data.json and re-render the mockup. Cheap to do; encourage when the original feels off-domain.

2.6 Surface risks and unknowns

Name what could go wrong or is unclear. Not to solve — just to surface.

Ask: "Are any of these blockers, or acceptable deferred scope?"

2.7 Scope boundary

State explicitly what is in and what is out.

Out-of-scope items must be one of:

• (a) Something the user explicitly excluded ("no notifications for v1")
• (b) An obvious near-neighbor a reader would expect to see flagged ("no due dates" — common in PM systems, worth naming)
• (c) The alternative side of a default chosen above ("chose soft-delete on projects → hard-delete is out")

Do NOT enumerate every feature that exists in similar products but isn't in this one. A 9-item out-of-scope list invented from category knowledge is noise, not boundary-setting.

Ask: "Does this match your intent, or should anything move?"

---

Phase 3 — Capture

Produce docs/brainstorm.md for the whole project (not per feature). Only one of these per project. (docs/ROADMAP.md was written or updated during Phase 0 — this phase does not touch it.)

Capture rules:

1. Document, not transcript. Each section reads as a coherent narrative with contextual headers. A future reader (no access to the conversation) should understand each section.
2. Quote when the framing is the substance. See Voice and Substance Discipline at the top of this skill. Verbatim for workflows, jobs-to-be-done, the why, and the user's domain language. Fold the rest.
3. Agent contributions stay invisible. If the agent proposed a feature, an entity, or a decision and the user accepted, it appears as part of the project — not as "suggested by agent."
4. Nothing is invented. If neither the user said it nor the agent surfaced it explicitly, it doesn't appear.
5. Project-level scope. This document captures the workflow that cuts across multiple features and orients new readers to the project as a whole. Per-feature detail belongs in each feature's spec.md, written later by feather-spec.
6. Substantive utterances are preserved in ## In the user's own words — even where folded into prose above. Cap at ~5 quotes per session; if you exceed that, the threshold is too loose.

brainstorm.md format (project-level)

Produce docs/brainstorm.md for the whole project. Only one of these per project (not per feature). It captures the workflow that cuts across multiple features and orients new readers to the project as a whole. Per-feature detail belongs in each feature's spec.md.

# Project: <Name>

## What this project is
*2–3 sentences: the big-picture motivation. What problem this project solves and for whom, at the system level. This is broader than any one feature.*

[content]

## Who uses it
*All actors across the whole system, with their roles. More inclusive than any single feature's "Who uses it" section. Includes occasional users, admins, integrations.*

[content]

## Today's workflow
*The user's whole life today, near-verbatim from how they describe it. Cuts across what will become multiple features. Captures the gritty, real flow — including the workarounds. The "5 reveals" mapping (Steps→Features needed, Handoffs→Integration points, Delays→Automation opportunities, Workarounds→Pain points, Repetition→Templates/defaults candidates) helps extract structure here.*

[content]

## Pain points
*The friction that motivates the whole project. Cross-feature. Each pain point traceable to something in Today's workflow above.*

[content]

## Features
*The decomposition: workflow → multiple features. Each feature gets a one-line role plus a path pointer to its spec. Listed in priority order (which to build first).*

- **<feature-name>** — <one-line role>. See `features/<feature-name>/spec.md`
- **<feature-name>** — <one-line role>. See `features/<feature-name>/spec.md`

## How features connect
*Integration points between features. Where data flows. Where one feature's output becomes another feature's input. Useful for ordering — you cannot build the consumer before the producer.*

[content]

## App shell
*The chrome that wraps every feature. Sidebar nav, top bar, command palette, notifications/toasts, modal style, page-layout pattern. Each feature's screens render inside this shell. Validated as part of the project mockup at `docs/mockup.html`.*

- **Sidebar** — <bullets describing nav, collapse behavior, footer>
- **Top bar** — <bullets: app name, search/command bar, user menu, notifications>
- **Command palette** — <bullets: ⌘K behavior, fuzzy search scope, quick actions>
- **Toasts** — <position, dismiss behavior, when used>
- **Modals** — <anchor, backdrop, when used>
- **Page layout** — <sidebar width, collapsed width, main content layout pattern>

## Project-level open questions
*Open questions that span features or do not belong to any single feature. Feature-specific questions belong in that feature's `spec.md` Open Questions section.*

[content]

## In the user's own words
*Substance-tier verbatim quotes about the overall vision. Cap at ~5. Each quote prefaced with a short context line. Product-substance only — implementation tangents and process direction do not belong here.*

[content]

9 sections. Cross-feature scope. One page per project.

Template anti-patterns:

• ❌ Section headers that describe the question ("Workflow") instead of the content ("Today's workflow")
• ❌ Verbatim quotes for confirmations or picked-from-list answers
• ❌ Internal taxonomy in body text ("vague-but-bounded", "Capability type: Standard") — those serve the agent's routing, not the reader
• ❌ "User said X / user picked Y" attribution chatter — the document speaks in narrative prose
• ❌ Per-feature schema fields, screen detail, or business rules — that belongs in each feature's spec.md, not here
• ❌ Implementation tangents in ## In the user's own words — quotes there are product-substance only

---

Phase 4 — Handoff

Commit prompt (mandatory before spec handoff)

Brainstorm produces real source-of-truth artifacts (docs/brainstorm.md, docs/ROADMAP.md, docs/sample-data.json, docs/mockup.html). These belong in git as a discrete commit before the spec phase begins — otherwise a later pivot or revert can entangle brainstorm changes with spec changes, and git history loses "brainstorm complete" as a moment.

List what was created/changed and propose a commit:

"Brainstorm phase produced these files:

• docs/brainstorm.md (new — project-level discovery + app shell)
• docs/ROADMAP.md (new or updated — features inventory)
• docs/sample-data.json (new — realistic sample data for the prototype)
• docs/mockup.html (new — interactive project-wide prototype)

Proposed commit message:

brainstorm:

Project-level discovery: workflow, pain points, decomposition into N features, app shell. Interactive prototype (mockup.html + sample-data.json) generated for layout validation.

Three ways to reply:

• 'commit' — I'll stage and commit these files with the message above
• 'edit message: ' — change the commit message, then commit
• 'skip commit' — leave the work uncommitted (you'll commit manually later)"

If the user picks commit, run git add on the listed files and git commit with the proposed message. Then proceed to the spec handoff. If edit message, use the new message. If skip commit, proceed without committing — the user takes responsibility for the eventual commit.

Spec authoring handoff

After the commit prompt resolves, slim handoff — the user just lived this; no need to recap the artifact:

"docs/brainstorm.md is written and committed. Ready to spec the first feature? Say 'write the spec' to continue, or note any changes first."

(If commit was skipped: "docs/brainstorm.md is written (uncommitted). Ready to spec the first feature?...")

Do not auto-proceed. The user confirms.

When confirmed, hand off to feather-spec. feather-spec consumes:

• docs/brainstorm.md — for project-level context: workflow, pain points, decomposition into features, app shell, the user's domain language
• docs/mockup.html — for layout: derive each feature's inline ASCII zone diagrams in spec.md Section 5 from the corresponding sections of the project mockup

…and produces per-feature spec artifacts (spec.md, design.md, decisions/ ADRs, tasks.md) for whichever feature was selected from the project's Features list. Multi-feature projects route through the Features list one feature at a time — each feature gets its own spec session.

Forward-link discipline: docs/brainstorm.md references future features/<name>/spec.md paths in the Features section (those paths are predictable and stable even before the specs are written). It does not reference content inside those specs. Per-feature specs read on their own; the project-level brainstorm reads on its own.

---

Anti-Patterns

❌ Don't	✅ Do
Paraphrase the user's workflow	Quote it directly
Silently resolve a contradiction	Surface both quotes, ask user to resolve
Delete a contradicted statement	Keep it with a resolution note
Recommend before presenting options	Present options first
Ask multiple questions at once	One question at a time
Auto-proceed to spec after brainstorm	Wait for user confirmation
Invent screens the user didn't mention	Surface as "suggested by agent" and confirm
Generate per-feature mockup HTML sidecars (features/<f>/screens/<screen>-NN.html)	Mockup is project-level (docs/mockup.html); per-feature mockups fragment what should be one coherent app design
Skip Phase 2.5 prototype build	Prototype is the validation moment — sample-data.json + mockup.html let the user feel the system, not just read about it
Silently pick one feature when input was multi-feature	Surface the multi-feature detection; capture all features in docs/brainstorm.md Features section + ROADMAP.md, then ask which to spec first
Expose internal taxonomy ("vague-but-bounded", "Capability type: Standard")	Internal routing only — speak in plain user terms
Pick technology in brainstorm (auth library, framework, DB)	Defer to design.md — brainstorm captures intent, not tech
Narrate "writing brainstorm.md", "handing off to feather-spec" repeatedly	Mention the artifact once at the end. Talk about the work, not the artifact
Use auto mode / "be efficient" as cover to skip mode menu or scope confirmation	Mode and scope are shaping decisions; always confirm. Auto mode applies to routine decisions only
Open with environmental observations ("Fresh project directory", "I see you have...")	Engage with the user's request directly; environment is internal context, not opening line
Silently announce a chosen mode ("I'll move in assumption mode")	Show the menu; let the user pick. If they don't pick within one turn, then nudge — but never decide for them
Bundle scope confirmation and mode menu in the same turn	One gate per turn. Scope confirmation ends the turn; mode menu starts a new turn after the user replies
Embed substantive sub-questions inside a confirmation prompt ("sound right? and is X its own feature?")	Confirmation questions stay binary; substantive sub-questions get their own turn after confirmation
Use the word "capability" in user-facing prose	Internal vocabulary only — say "feature", "shape", "kind of system", or the thing the user named
Open with a yes/no scope confirmation ("Reading this as one feature")	Open with a reflect + 2–4 shape options the user can react to (broadens before narrowing)
Show option lists without numbers (just bullets or plain markers)	Number choices (1, 2, 3) so the user can reply with a single character — Concierge Default
Add escape-hatch parentheticals that pre-announce the next gate ("if you'd rather walk through your current process…")	Trust the next gate to handle it. Each gate offers what it offers; don't preview the next one
Name a framework, library, auth provider, DB, or host in brainstorm output ("Convex Auth", "Next.js", "Postgres")	Say what the user does ("email sign-in"); defer tech to design.md
List schema fields under entities in brainstorm (name, assignee, status, …)	One-line "what this represents" only — fields live in design.md
Use emoji (✅ ✏️ ❌) as input syntax the user must type back	Phrase-based replies ('all ok', 'change 5 to ...', 'show alternatives for #5'); emoji fine in your output, never as required input
Rely on implicit "silence means keep" without naming the "yes to all" phrase	Always suggest the explicit phrase ('all ok', 'yes to all', 'looks good') so the user knows what to type
Reuse 1 / 2 / 3 to mean response modes when 1 / 2 / 3 already mean item references in the picture	One number scheme at a time; numbers refer to items, response modes are named phrases
Hand off to feather-spec without a commit prompt for the brainstorm artifacts	Phase 4 commit prompt is mandatory — docs/brainstorm.md + ROADMAP.md + sample-data.json + mockup.html get a discrete commit before the spec phase begins
Name an ADR file with literal ADR prefix (ADR0002-foo.md)	Filename is 0002-foo.md; the parent folder decisions/ already implies ADR. Cross-link label is [ADR-0002] — that's the human-reading form, separate from the filename
Let docs/mockup.html and docs/brainstorm.md drift apart as the conversation evolves	Mockup-update protocol (Phase 2.5.4) — when a new entity, screen, behavior, or shell element surfaces, update mockup alongside the doc
Generate sample data with placeholder names (Jane Doe, John Smith) and generic project examples ("Project A", "Sample Task")	Use the user's actual names, project examples, and domain language; offer to refresh sample data if the original feels off-domain
Quote implementation tangents in ## In the user's own words ("convex auth doesn't support X", "use Resend")	That section is product-substance only — implementation tangents belong in design.md later
Quote process direction in ## In the user's own words ("show me a visual mockup", "give me 3 options")	Process direction is about how the agent operated, not what's being built — drop
Quote agent-meta feedback in ## In the user's own words ("normally I see options side by side")	That's feedback on the skill, belongs in feather-heal-skill input — not in the project brainstorm
Quote picked-from-list confirmations in ## In the user's own words ("stick with defaults", "yes, B")	Record the choice in the relevant prose section; confirmations are not substance
List "open questions" that restate items already addressed elsewhere in the doc	Open questions must be net-new; if it's already addressed as an alternative or a feature item, drop it from the open-questions list
Capture per-feature schema, screens, or business rules in docs/brainstorm.md	Project-level brainstorm is for cross-feature workflow + decomposition. Per-feature detail belongs in each feature's spec.md, written later by feather-spec
Ask the user to mark ✅/✏️/❌ across an unstructured long list, then offer "looks good" as escape	Number every item; invert the default — silence means keep, user only flags exceptions
Bundle multiple decisions in one bullet ("sort by status then date, newest first")	One decision per numbered line so the user can ✏️ each independently
Dump more than one viewport-worth (~25 lines) in a single assumption-mode turn	Chunk by section (workflow → reply → pain points → reply → features → reply → open questions); each turn = one screen; numbering continues across turns
Let any one section exceed 7 numbered items	Roll up (combine related decisions) or push down (it's design.md detail) — splitting past 7 doesn't fix the granularity leak
Skip Phase 2.1 restatement in assumption mode because "the picture is the answer"	Restatement still gates the picture — one sentence in the user's words, then dive in
Skip Phase 2.5 prototype build because "the doc is enough"	The mockup is what lets the user feel the app — text alone misses layout, navigation, and sample-data realism issues that prototype interaction surfaces immediately
Capture committed answers in brainstorm — schema fields, behavior rules, screen-level FRs, scope commitments	Brainstorm records project-level workflow + decomposition; per-feature commitments live in each feature's spec.md. The brainstorm doc is a discovery record, not a spec
Accept the user's first specific framing without surfacing 1–2 alternatives	Even on clear inputs, broaden first (per Broadening Stance section). Bounding is spec's job, not brainstorm's
Surface internal routing taxonomy in user-facing brainstorm body — e.g., "Shape: self-contained feature with two closely-related entities", "Feature type: Standard", "vague-but-bounded"	Internal routing categories never appear in user-facing prose. Use plain language to describe what the system is; the routing classification is feather-spec's internal concern, derived from spec content