design-verification

What this skill does

# Design Verification

Verify a design document against the actual codebase to catch conflicts, gaps, and incorrect assumptions before implementation. This is the gate between "this sounds right" and "this will actually work."

**Announce at start:** "Running design-verification to check this design against the codebase for blockers and gaps."

## When to Use

- After writing or updating a design document
- Before creating a GitHub issue from a design
- Before writing an implementation plan
- When the user asks "will this work with our app?"

## Process

### Step 1: Load the Design Document

Find the design from the linked GitHub issue:

1. **If `issue` is in the lifecycle context** (the issue number was passed as an argument or set by `create-issue` earlier in the session):
   ```bash
   gh issue view <issue_number> --json body --jq '.body'
   ```
   Extract the content between `<!-- feature-flow:design:start -->` and `<!-- feature-flow:design:end -->` markers.
   - If markers are found: use the extracted content as the design document.
   - If markers are absent: the design has not been merged into the issue yet. Stop and instruct the user: "No design found in issue #<issue_number>. Run `feature-flow:design-document` first to merge the design into the issue."
   - If the extracted content is a reference link (`Design is too large to inline — see comment: <url>`): fetch the comment URL via `gh api <url> --jq '.body'` and use that content instead.

2. **If the user specified a file path directly** (legacy support for pre-2026-04-23 design docs in `docs/plans/`):
   Read the file at the specified path. Announce: "Loading design from file (legacy path): `<path>`."

3. **Fallback — no issue and no path:** Stop and instruct the user: "No design source found. Pass the issue number (`issue: N`) or a file path (`design_doc: /path/to/doc.md`)."

After loading, extract all proposed changes from the design content.

### Step 2: Load Project Context

Check for a `.feature-flow.yml` file in the project root:

1. If found, read the `platform`, `stack`, and `gotchas` fields
2. For each entry in `stack`, look for a matching reference file at `../../references/stacks/{name}.md` (relative to this skill's directory)
3. For the declared `platform`, load the platform reference from `../../references/platforms/{platform}.md` (use `mobile.md` for `ios`, `android`, or `cross-platform`)
4. If a stack has no matching reference file, note it and use `WebSearch` to research known gotchas for that technology

If `.feature-flow.yml` does not exist, offer to create it via auto-detection:

1. Detect platform and stack from project files (see `../../references/auto-discovery.md`)
2. Present detected context to user and ask for confirmation
3. If confirmed, write `.feature-flow.yml` and continue with the detected context
4. If declined, proceed with the base checklist only

See `../../references/project-context-schema.md` for the full schema documentation.

### Step 3: Explore the Codebase (Tagged Domains)

Launch parallel exploration agents to understand the areas affected by the design. Organize results into 5 tagged domains so each verification batch (Step 4) receives only its relevant context instead of the full exploration dump.

Use the Task tool with `subagent_type: "Explore"` and `model: "haiku"` (see `../../references/tool-api.md` — Task Tool).

Announce before dispatching: "Dispatching 5 exploration agents in parallel: schema, pipeline, ui, config, patterns."

Dispatch all 5 domain agents in a **single message** (parallel):

1. **Schema agent** — Migration files, ORM models, type definition files (`*.d.ts`, `types.ts`)
2. **Pipeline agent** — API route files, hook files, pipeline files, shared type consumers
3. **UI agent** — Component files, layout files, navigation components
4. **Config agent** — `tsconfig.json`, eslint config, `next.config.*`, `package.json`
5. **Patterns agent** — Directory structure (2-3 representative paths), naming convention samples (2-3 files), error handling examples

**Expected output per agent:** Each agent returns free-form text describing what it found. The orchestrator slots each agent's text output into `exploration_results` by the domain it was dispatched for (schema, pipeline, ui, config, or patterns). The orchestrator assigns the domain key — agents do not self-report it.

**Failure handling:** If an agent fails, retry it once. If it fails again, use an empty string for that domain's content and log a warning: "[domain] exploration failed — that domain's context will be absent from relevant batch agents." If an agent succeeds but finds no relevant files for the project (e.g., a UI-less CLI project has no component files), treat its output as an empty string — this is correct and safe to pass to batch agents.

**Aggregate results into `exploration_results`:**
```
exploration_results = {
  schema:   <content from schema agent>,
  pipeline: <content from pipeline agent>,
  ui:       <content from ui agent>,
  config:   <content from config agent>,
  patterns: <content from patterns agent>
}
```

### Step 4: Run Verification Checklist

Dispatch parallel verification agents to check the design against the codebase. Each agent handles a thematic batch of checklist categories.

**Read `references/checklist.md` for the full detailed checklist.** The checklist is partitioned into 8 batches (6 using `<!-- batch: N -->` markers in checklist.md, plus Batch 7 defined inline below, plus Batch 8 conditionally dispatched when `design_preferences` is present):

| Batch | Agent | Categories |
|-------|-------|------------|
| 1 | Schema & Types | 1. Schema Compatibility, 2. Type Compatibility |
| 2 | Pipeline & Components | 3. Pipeline/Flow, 4. UI Component Inventory, 5. Cross-Feature Impact |
| 3 | Quality & Safety | 6. Completeness, 7. Cost & Performance, 8. Migration Safety |
| 4 | Patterns & Build | 9. Internal Consistency, 10. Pattern Adherence, 11. Dependencies, 12. Build Compatibility |
| 5 | Structure & Layout | 13. Route & Layout Chain, 14. Structural Anti-Patterns |
| 6 | Stack/Platform/Docs | 15. Stack-Specific, 16. Platform-Specific, 17. Project Gotchas, 18. Documentation Compliance |
| 7 | Implementation Quality | 19. Type Narrowness, 20. Error Strategy Completeness, 21. Function Complexity Forecast, 22. Edge Case Enumeration, 23. Stack Pattern Compliance |
| 8 | Design Preferences | 24. Design Preferences Compliance |
| 9 | External Assumptions | 25. External Assumptions |

**`assumptions-only` flag:** If `assumptions-only` is present in ARGUMENTS, skip Batches 1–8 entirely and run only Batch 9. Announce: `Running assumption verification only (Batches 1-8 skipped).` Then proceed directly to Batch 9 dispatch below.

**Verification depth filtering:** Before dispatching, consult the Verification Depth table below. Only dispatch batches containing at least one applicable category for the design's scope. Pass the list of applicable categories to each agent so it skips non-applicable categories within its batch.

#### Dispatch

Use the Task tool with `subagent_type: "Explore"` and `model: "sonnet"` for Batches 1-5 and Batch 7 (see `../../references/tool-api.md` — Task Tool for correct parameter syntax). Launch all applicable batch agents in a **single message** to run them concurrently. Announce: "Dispatching N verification agents in parallel..." (If `assumptions-only` is in ARGUMENTS, only Batch 9 is dispatched — see the `assumptions-only` flag above.)

**Context passed to each agent:**

**Universal context (every batch):**
- The full design document content
- Its assigned checklist categories (partitioned from `references/checklist.md` using batch markers)
- The `.feature-flow.yml` content (for stack/platform/gotchas context)
- The list of applicable categories for this batch (from verification depth filtering)

In addition to the universal context above, each batch receives the following domain-filtered sections from `exploration_results` (p