design-document

What this skill does

# Design Document

Turn brainstorming decisions into a structured, implementable design document. The document serves as the single source of truth between brainstorming and implementation planning.

**Announce at start:** "Writing design document to capture the agreed design before implementation."

## When to Use

- After brainstorming a feature (decisions have been made)
- When the user has a clear idea of what to build and needs it documented
- Before writing an implementation plan
- When translating requirements into technical design

## Optional Args (used when invoked from orchestrator dispatch)

When invoked as a Pattern B consolidator subagent (per #251), the orchestrator passes these arguments so the skill can skip the hoisted-fanout step and write its structured return contract back to the lifecycle's in-progress state file:

- `findings_path: <absolute-path-to-findings-json>` — when set, the skill skips Step 1's Explore-agent dispatch and reads the pre-fetched findings from this JSON file instead. The file contains the consolidated `{schema, pipeline, ui, format, code, ...}` findings produced by the orchestrator-side parallel fanout. Format: `{"agents": [{"area": string, "findings": string[]}, ...]}`.
- `write_contract_to: <absolute-path-to-in-progress-yml>` — when set, writes the return contract to `phase_summaries.<phase_id>.return_contract` in that YAML file after Step 4 (issue body merge) completes (see Step 8 below).
- `phase_id: <bucket-name>` — identifies which **`phase_summaries` bucket** to write into. Must be one of the four fixed buckets: `brainstorm`, `design`, `plan`, or `implementation`. If absent when `write_contract_to` is set, defaults to `design` (the bucket that contains the `design-document` lifecycle step). **Do not confuse `phase_id` with the contract's own `phase` field** — `phase_id` is the bucket key (`design`); the contract's `phase` field is the lifecycle step name (`design-document`) per #251's locked spec.

All three args are optional. If `findings_path` is absent, Step 1 dispatches Explore agents as before. If `write_contract_to` is absent, Step 8 is skipped — the skill behaves identically to its inline-invocation form.

## Process

### Step 1: Gather Context

Collect the inputs needed to write the document:

1. **From the conversation:** Extract all decisions made during brainstorming — scope, approach, UX flow, data model, technical choices
2. **From the codebase and documentation:** Dispatch parallel Explore agents to gather context from multiple areas simultaneously.

**Pattern B consolidator-mode early exit:** If `findings_path` is set in ARGUMENTS, the orchestrator has already executed the parallel fanout. Read the JSON at that path, treat its `agents[]` array as the unified context summary, and skip the entire `#### Parallel Context Gathering` and `#### Failure Handling` subsections below. Jump directly to `#### Consolidation`. The clarification `AskUserQuestion` at the end of Consolidation is still suppressed when `yolo: true` or `express: true` is set (existing behavior). This branch exists for the Pattern B subagent dispatch wired in `skills/start/SKILL.md` — see "Design Document — Pattern B Dispatch" in that file.

#### Parallel Context Gathering

Launch 3-4 Explore agents in a **single message** using the Task tool with `subagent_type: "Explore"` and `model: "haiku"` (see `../../references/tool-api.md` — Task Tool for correct parameter syntax). Announce: "Dispatching N context-gathering agents in parallel..."

| Agent | Assignment | Always? |
|-------|-----------|---------|
| Format patterns | Read existing design docs in `docs/plans/` and extract document structure, section patterns, and conventions. **Read-only — never writes to `docs/plans/`.** | Yes |
| Stack & dependencies | Examine dependency files (`package.json`, config files), project structure, and tech stack conventions | Yes |
| Relevant code | Search for and read source files related to the feature being designed (e.g., existing components, routes, hooks, models in the affected areas) | Yes |
| Documentation (Context7) | If `.feature-flow.yml` has a `context7` field, the Context7 MCP plugin is available (see `../../references/tool-api.md` — Context7 MCP Tools for availability check), AND no documentation lookup step was already run in the `start` lifecycle — query relevant Context7 libraries for current patterns the design should follow. Skip this agent if any condition is not met. | Conditional |

**Context passed to each agent:**
- Feature description (from brainstorming output or issue body)
- Specific gathering assignment from the table above
- For the Documentation agent: library IDs from `.feature-flow.yml` `context7` field

**Expected return format per agent:**

```
{ area: string, findings: string[] }
```

#### Failure Handling

If an agent fails or crashes, retry it once. If it fails again, skip it and log a warning: "[Agent name] failed — [area] context skipped. Continuing with available results."

#### Consolidation

After all agents complete, synthesize their findings into a unified context summary for writing the design document.

If the conversation does not contain enough decisions, ask the user to clarify. Use `AskUserQuestion` — one question at a time, with options when possible.

**YOLO behavior:** If `yolo: true` is in the skill's `ARGUMENTS`, do not call `AskUserQuestion` for clarification. Instead, answer the questions from available context (brainstorming output, issue body, codebase analysis) and announce each: `YOLO: design-document — [question] → [answer]`. If critical information is genuinely missing (not inferable from any source), note it as `[TBD]` in the design document rather than guessing.

**Express behavior:** If `express: true` is in the skill's `ARGUMENTS`, apply the same clarification suppression as YOLO. Do not call `AskUserQuestion` for clarification. Answer questions from available context and announce each: `Express: design-document — [question] → [answer]`. Note `[TBD]` for genuinely missing information.

### Step 2: Determine Sections

Select sections based on what the feature requires. Not every feature needs every section.

**Required sections:**
- **Overview** — What the feature does, in 2-3 sentences
- **User Flow** — Step-by-step from the user's perspective
- **Patterns & Constraints** — Error handling strategy, type narrowness, performance constraints, and stack-specific patterns that implementation must follow
- **Scope** — What is included and what is explicitly excluded

**Include when applicable:**

| Section | Include When |
|---------|-------------|
| Example | The feature has input/output that benefits from a concrete example |
| Data Model Changes | The feature requires new or modified database tables/columns |
| Migration Requirements | Database migrations are needed (numbered list) |
| API / Integration | The feature calls external APIs or introduces new internal API routes |
| Pipeline / Architecture | The feature involves multi-step processing, async flows, or new hooks |
| LLM Integration | The feature uses an LLM (model, prompt design, output format, validation) |
| UI Adaptations | Existing UI components need modification for the new feature |
| New Components | New UI components, hooks, or utilities need to be built |

**Include when platform is mobile (ios, android, cross-platform):**

Check for `.feature-flow.yml` in the project root to determine the platform. If `platform` is `ios`, `android`, or `cross-platform`, add these sections:

| Section | Required | Purpose |
|---------|----------|---------|
| Feature Flag Strategy | Yes | How the feature can be killed server-side without an app update |
| Rollback Plan | Yes | Multi-version compatibility strategy since "revert deploy" doesn't work |
| API Versioning | If API changes | How old app versions interact with the new backend |
| Device Compatibility | Yes | Minimum OS versions, screen sizes, accessibility |

See