blueprint:capture

What this skill does

# Capture Context

**COMMAND:** Extract decisions, rationale, and context from the current conversation and persist them into the appropriate blueprint documents — across the code/architecture tree, `DESIGN.md`, and the design/UX tree.

## Execute

1. **Detect design availability** — Glob for `DESIGN.md` and `design/ux-decisions/`. `DESIGN.md` may exist without the opt-in design tree. If `design/ux-decisions/` doesn't exist, UX decisions are skipped — never silently filed as ADRs — but cross-cutting design rules can still update `DESIGN.md` when it exists.

2. **Scan** the current conversation for:
   - Architectural decisions (tech choices, code-level approaches, trade-offs)
   - **UX decisions** (only if `design/` exists): interaction model, navigation, modal vs page, empty/error states, motion
   - **Cross-cutting design rules** (only if `DESIGN.md` exists): visual rules, token usage, type scale, voice/tone, broad prohibitions
   - Design-intent confirmations: statements that a current UI choice is deliberate rather than coincidental
   - Requirements discovered or refined during discussion
   - Patterns agreed upon (any subject — code, schema, UI)
   - Open questions that were resolved
   - Implementation state changes (progress, blockers, new constraints)

3. **If argument provided:** Focus capture on that specific topic only.

4. **If design content was discussed but the right design artifact doesn't exist:** Note this in the preview. Don't misfile it.
   - UX decision but no `design/` tree: suggest `/blueprint:onboard-design`
   - Cross-cutting design rule but no `DESIGN.md`: suggest `/blueprint:onboard-design` to scaffold it, or create `DESIGN.md` only if the user explicitly confirms in this capture flow

5. **Read** existing docs to avoid duplicates:
   - `docs/adrs/*.md` — existing architectural decisions
   - `docs/specs/features/*.md` — existing feature specs
   - `patterns/good/` and `patterns/bad/anti-patterns.md` — existing patterns
   - `DESIGN.md` — cross-cutting design rules (if present)
   - `design/ux-decisions/*.md` — existing UX decisions (if tree exists)

6. **Classify** each captured item — **respect tree separation**, never file design content under `docs/` or code content under `design/`. Design destinations are only valid when `design/` exists:

   | Type | Destination | Action |
   |------|-------------|--------|
   | New architectural decision | `docs/adrs/NNN-slug.md` | Create Draft ADR |
   | Refinement of existing ADR | Existing ADR | Update (add context, resolve TODOs, promote Draft→Active) |
   | New UX decision | `design/ux-decisions/NNN-slug.md` | Create Draft UX decision |
   | Refinement of existing UX decision | Existing UX decision | Update |
   | Cross-cutting design rule | `DESIGN.md` | Append or update the relevant short section |
   | New feature/requirement | `docs/specs/features/slug.md` | Create with maturity: Exploring |
   | Refinement of existing feature | Existing feature spec | Update requirements, implementation state, maturity |
   | Implementation progress | Existing feature spec | Update Implementation State section |
   | Good pattern agreed on (any subject) | `patterns/good/name.ext` | Create pattern file |
   | Anti-pattern identified (any subject) | `patterns/bad/anti-patterns.md` | Append section |
   | Open question resolved | Existing spec / ADR / UX decision | Remove TODO, fill in answer |

7. **Preview** — Show the user what will be captured before writing. If design content was scanned but skipped due to missing tree, list those skipped items separately. **Only show the "Skipped" block when at least one design item was actually scanned and skipped** — if the conversation had no UX/design content, omit it entirely (don't narrate design-tree absence as a reason for not capturing things that were never there):
   ```
   Found N items to capture:

   1. [UPDATE] docs/specs/features/foo.md — Add implementation state, advance maturity to Building
   2. [CREATE] docs/adrs/005-caching-strategy.md — Draft ADR for Redis caching decision

   Skipped (design tree not set up — run /blueprint:onboard-design to capture these):
   - 1 UX decision (modal vs full page for confirmations)
   - 1 DESIGN.md rule (imperative CTA voice) — DESIGN.md not present
   ```

8. **Confirm** — Ask: "Proceed with all, or select specific items?"

9. **Write** confirmed items using templates from `_templates/TEMPLATES.md`

10. **Report** what was captured and where (and what was skipped)

## Rules

- **Draft by default** for new ADRs — conversation decisions are emerging, not final
- **Never overwrite** existing content without showing the diff
- **Update > Create** — prefer updating existing docs over creating new ones
- **Skip obvious** — don't capture things already documented or derivable from code
- **Code is not design rationale** — only capture UX intent when the conversation confirms why a UI choice is deliberate
- **DESIGN.md is for broad rules** — put cross-cutting design rules there, not in UX decisions. Do not duplicate an existing DESIGN.md rule into a UX decision; reference it.
- **Implementation State is first-class** — always update the Implementation State section of affected feature specs

## Output

```
Captured from conversation:

- Created docs/adrs/005-caching-strategy.md (Draft)
- Updated docs/specs/features/notifications.md:
  - Maturity: Exploring → Building
  - Added 2 requirements
  - Updated implementation state: "Database schema designed"
- Updated docs/adrs/003-shell-hooks.md: resolved 1 TODO

Context is now persisted. Safe to start a new session.
```