Brainstorm - Requirements Discovery (AI Coding Enhanced)

Guide AI through collaborative requirements discovery before implementation, optimized for AI coding workflows:

• Task-first (capture ideas immediately)

• Action-before-asking (reduce low-value questions)

• Research-first for technical choices (avoid asking users to invent options)

• Diverge → Converge (expand thinking, then lock MVP)

When to Use

Triggered from $start when the user describes a development task, especially when:

• requirements are unclear or evolving

• there are multiple valid implementation paths

• trade-offs matter (UX, reliability, maintainability, cost, performance)

• the user might not know the best options up front

Core Principles (Non-negotiable)

Task-first (capture early) Always ensure a task exists at the start so the user's ideas are recorded immediately.

Action before asking If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.

One question per message Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.

Prefer concrete options For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.

Research-first for technical choices If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.

Diverge → Converge After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope.

No meta questions Do not ask "should I search?" or "can you paste the code so I can continue?" If you need information: search/inspect. If blocked: ask the minimal blocking question.

Step 0: Ensure Task Exists (ALWAYS)

Before any Q&A, ensure a task exists. If none exists, create one immediately.

• Use a temporary working title derived from the user's message.

• It's OK if the title is imperfect — refine later in PRD.

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)

Create/seed prd.md immediately with what you know:

brainstorm: <short goal>

Goal

<one paragraph: what + why>

What I already know

• <facts from user message>
• <facts discovered from repo/docs>

Assumptions (temporary)

• <assumptions to validate>

Open Questions

• <ONLY Blocking / Preference questions; keep list short>

Requirements (evolving)

• <start with what is known>

Acceptance Criteria (evolving)

• <testable criterion>

Definition of Done (team quality bar)

• Tests added/updated (unit/integration where appropriate)
• Lint / typecheck / CI green
• Docs/notes updated if behavior changes
• Rollout/rollback considered if risky

Out of Scope (explicit)

• <what we will not do in this task>

Technical Notes

• <files inspected, constraints, links, references>
• <research notes summary if applicable>

Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS)

Before asking questions like "what does the code look like?", gather context yourself:

Repo inspection checklist

• Identify likely modules/files impacted

• Locate existing patterns (similar features, conventions, error handling style)

• Check configs, scripts, existing command definitions

• Note any constraints (runtime, dependency policy, build tooling)

Documentation checklist

• Look for existing PRDs/specs/templates

• Look for command usage examples, README, ADRs if any

Write findings into PRD:

• Add to What I already know

• Add constraints/links to Technical Notes

Step 2: Classify Complexity (still useful, not gating task creation)

Complexity Criteria Action

Trivial Single-line fix, typo, obvious change Skip brainstorm, implement directly

Simple Clear goal, 1–2 files, scope well-defined Ask 1 confirm question, then implement

Moderate Multiple files, some ambiguity Light brainstorm (2–3 high-value questions)

Complex Vague goal, architectural choices, multiple approaches Full brainstorm

Note: Task already exists from Step 0. Classification only affects depth of brainstorming.

Step 3: Question Gate (Ask ONLY high-value questions)

Before asking ANY question, run the following gate:

Gate A — Can I derive this without the user?

If answer is available via:

• repo inspection (code/config)

• docs/specs/conventions

• quick market/OSS research

→ Do not ask. Fetch it, summarize, update PRD.

Gate B — Is this a meta/lazy question?

Examples:

• "Should I search?"

• "Can you paste the code so I can proceed?"

• "What does the code look like?" (when repo is available)

→ Do not ask. Take action.

Gate C — What type of question is it?

• Blocking: cannot proceed without user input

• Preference: multiple valid choices, depends on product/UX/risk preference

• Derivable: should be answered by inspection/research

→ Only ask Blocking or Preference.

Step 4: Research-first Mode (Mandatory for technical choices)

Trigger conditions (any → research-first)

• The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention

• The user asks for "best practice", "how others do it", "recommendation"

• The user can't reasonably enumerate options

Research steps

• Identify 2–4 comparable tools/patterns

• Summarize common conventions and why they exist

• Map conventions onto our repo constraints

• Produce 2–3 feasible approaches for our project

Research output format (PRD)

Add a section in PRD (either within Technical Notes or as its own):

Research Notes

What similar tools do

• ...
• ...

Constraints from our repo/project

• ...

Feasible approaches here

Approach A: <name> (Recommended)

• How it works:
• Pros:
• Cons:

Approach B: <name>

• How it works:
• Pros:
• Cons:

Approach C: <name> (optional)

• ...

Then ask one preference question:

• "Which approach do you prefer: A / B / C (or other)?"

Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding

After you can summarize the goal, proactively broaden thinking before converging.

Expansion categories (keep to 1–2 bullets each)

Future evolution

• What might this feature become in 1–3 months?

• What extension points are worth preserving now?

Related scenarios

• What adjacent commands/flows should remain consistent with this?

• Are there parity expectations (create vs update, import vs export, etc.)?

Failure & edge cases

• Conflicts, offline/network failure, retries, idempotency, compatibility, rollback

• Input validation, security boundaries, permission checks

Expansion message template (to user)

I understand you want to implement: <current goal>.

Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):

1. Future evolution: <1–2 bullets>
2. Related scenarios: <1–2 bullets>
3. Failure/edge cases: <1–2 bullets>

For this MVP, which would you like to include (or none)?

1. Current requirement only (minimal viable)
2. Add <X> (reserve for future extension)
3. Add <Y> (improve robustness/consistency)
4. Other: describe your preference

Then update PRD:

• What's in MVP → Requirements

• What's excluded → Out of Scope

Step 6: Q&A Loop (CONVERGE)

Rules

One question per message

Prefer multiple-choice when possible

After each user answer:

• Update PRD immediately

• Move answered items from Open Questions → Requirements

• Update Acceptance Criteria with testable checkboxes

• Clarify Out of Scope

Question priority (recommended)

• MVP scope boundary (what is included/excluded)

• Preference decisions (after presenting concrete options)

• Failure/edge behavior (only for MVP-critical paths)

• Success metrics & Acceptance Criteria (what proves it works)

Preferred question format (multiple choice)

For <topic>, which approach do you prefer?

1. Option A — <what it means + trade-off>
2. Option B — <what it means + trade-off>
3. Option C — <what it means + trade-off>
4. Other — describe your preference

Step 7: Propose Approaches + Record Decisions (Complex tasks)

After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):

Based on current information, here are 2–3 feasible approaches:

Approach A: <name> (Recommended)

• How:
• Pros:
• Cons:

Approach B: <name>

• How:
• Pros:
• Cons:

Which direction do you prefer?

Record the outcome in PRD as an ADR-lite section:

Decision (ADR-lite)

Context: Why this decision was needed Decision: Which approach was chosen Consequences: Trade-offs, risks, potential future improvements

Step 8: Final Confirmation + Implementation Plan

When open questions are resolved, confirm complete requirements with a structured summary:

Final confirmation format

Here's my understanding of the complete requirements:

Goal: <one sentence>

Requirements:

• ...
• ...

Acceptance Criteria:

• ...
• ...

Definition of Done:

• ...

Out of Scope:

• ...

Technical Approach: <brief summary + key decisions>

Implementation Plan (small PRs):

• PR1: <scaffolding + tests + minimal plumbing>
• PR2: <core behavior>
• PR3: <edge cases + docs + cleanup>

Does this look correct? If yes, I'll proceed with implementation.

Sync PRD to External Tracker

If lifecycle hooks are configured with a sync action, sync the finalized PRD:

TASK_JSON_PATH="$TASK_DIR/task.json" python3 .trellis/scripts/hooks/linear_sync.py sync

Subtask Decomposition (Complex Tasks)

For complex tasks with multiple independent work items, create subtasks:

Create child tasks

CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR") CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")

Or link existing tasks

python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"

PRD Target Structure (final)

prd.md should converge to:

<Task Title>

Goal

<why + what>

Requirements

• ...

Acceptance Criteria

• ...

Definition of Done

• ...

Technical Approach

<key design + decisions>

Decision (ADR-lite)

Context / Decision / Consequences

Out of Scope

• ...

Technical Notes

<constraints, references, files, research notes>

Anti-Patterns (Hard Avoid)

• Asking user for code/context that can be derived from repo

• Asking user to choose an approach before presenting concrete options

• Meta questions about whether to research

• Staying narrowly on the initial request without considering evolution/edges

• Letting brainstorming drift without updating PRD

Integration with Start Workflow

After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's Phase 2: Prepare for Implementation:

Brainstorm Step 0: Create task directory + seed PRD Step 1–7: Discover requirements, research, converge Step 8: Final confirmation → user approves ↓ Task Workflow Phase 2 (Prepare for Implementation) Code-Spec Depth Check (if applicable) → Research codebase (based on confirmed PRD) → Configure code-spec context (jsonl files) → Activate task ↓ Task Workflow Phase 3 (Execute) Implement → Check → Complete

The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.

Related Commands

Command When to Use

$start

Entry point that triggers brainstorm

$finish-work

After implementation is complete

$update-spec

If new patterns emerge during work