blueprint:decide

What this skill does

# Record Decision

**COMMAND:** Capture a decision or design rule with its rationale. Triage between architectural decisions (ADRs), UX decisions, cross-cutting `DESIGN.md` rules, feature specs, and NFRs — write to the correct place.

## Execute

1. **Parse** argument for topic and rationale
2. **Detect design availability** — Glob for `DESIGN.md` and `design/ux-decisions/` (or any `design/` subdirectory). Design tree is **opt-in** — if it doesn't exist, UX decisions are unavailable, but `DESIGN.md` rules are still available when the file exists or the user agrees to scaffold it.
3. **Classify** each concern in the input (see Classification below). UX decision classification is only available when the design tree exists. Cross-cutting `DESIGN.md` rules are available when `DESIGN.md` exists, or when the user agrees to scaffold it.
4. **If strong UX signal but no design tree:** Pause and warn the user (see "Strong UX Signal Without Tree" below). Do NOT silently misfile UX content as an ADR.
5. **If mixed or misclassified:** Separate concerns into their document types
6. **Check** the relevant location for existing decisions (create dir if needed):
   - Architectural → `docs/adrs/`
   - UX (only if `design/` exists) → `design/ux-decisions/`
   - Cross-cutting design rule → `DESIGN.md` at repo root (read existing if present; offer to scaffold once if absent)
7. **Detect** conflicts with existing decisions or rules in the same location
8. **Create** file(s) per concern type
9. **Report** what was created and where

### Quiet on design when irrelevant

Do NOT narrate design triage, design-tree absence, or "no design tree" reasoning when **both** of the following hold:

- The input is unambiguously architectural (tech choice, library, infra, runtime/framework/database, code-level pattern, "[X] over [Y]" technical) — i.e. it has no UX/design signals from the Classification table.
- Neither `design/` nor `DESIGN.md` exists in the repo.

In that case, skip steps 2 and 4 in your user-visible output entirely. Just create the ADR and report it. Phrases like "Pure architectural decision, no design tree → ADR-NNN", "design tree not set up", or "filing as ADR since no design exists" are noise here — the design machinery is irrelevant to a backend/library/CLI repo deciding on a database.

Surface design-related triage only when:
- The input has UX/design signals (then handle per "Strong UX Signal Without Tree"), **or**
- The repo has `design/` or `DESIGN.md` (then triage between trees is meaningful).

## Classification

Before creating files, classify each distinct concern in the input:

| Signal | Type | Destination | Available |
|--------|------|-------------|-----------|
| Tech choice, library, infra, runtime/framework/database, code-level design pattern, "[X] over [Y]" technical | Architectural | ADR (`docs/adrs/NNN-[slug].md`) | Always |
| User flow, navigation choice, "modal vs page", confirmation pattern, copy/voice, empty/error/loading state, interaction model, layout, visual hierarchy, motion, a11y trade-off | UX | UX decision (`design/ux-decisions/NNN-[slug].md`) | Only if `design/` tree exists |
| Broad design rule, token usage, type scale, voice/tone, palette limit, "never use [X] on any screen", "all CTAs..." | Design rule | `DESIGN.md` | If present, or user agrees to scaffold |
| "users can", feature behavior, workflow, user story | Functional | Feature spec (`docs/specs/features/`) | Always (redirect to `/blueprint:require`) |
| Latency, throughput, uptime, encryption, SLA, scalability target | Non-functional | NFR (`docs/specs/non-functional/`) | Always (redirect to `/blueprint:require`) |

**Tree separation is strict.** UX decisions live in `design/ux-decisions/`, NEVER in `docs/adrs/`. Different reviewers own each tree.

**Design tree is opt-in.** If `design/` does not exist in the repo, do NOT route anything as a UX decision — even if the input looks like one. See "Strong UX Signal Without Tree" below.

**Cross-cutting UI rules belong in `DESIGN.md`, not as a UX decision.** UX decisions are *per-context choices with alternatives considered* ("modal vs full page for destructive confirmation — chose modal because..."). If the input is really a cross-cutting rule that applies broadly with no alternatives ("never use more than 3 colours on a screen", "all destructive actions require confirmation", "imperative voice for CTAs"), route it to `DESIGN.md` at the repo root — the community-format design context file.

If `DESIGN.md` exists: update the relevant short section. If it does not exist, ask once:
```
This sounds like a cross-cutting design rule, which belongs in DESIGN.md.
DESIGN.md does not exist yet. Scaffold it and add this rule?

Options:
- Scaffold DESIGN.md and add the rule
- Capture as UX decision instead
- Skip
```
Never duplicate a `DESIGN.md` rule into a UX decision; reference it instead.

**If input mixes types:**
1. Extract the architectural decision → create ADR
2. Extract the UX decision (only if tree exists) → create UX decision (separate numbering, separate file)
3. Extract cross-cutting design rules → update `DESIGN.md` if present or confirmed
4. Extract functional requirements → suggest `/blueprint:require`
5. Extract NFR targets → suggest `/blueprint:require`
6. Report all files created or updated

**If input is purely functional or non-functional** (no decision rationale):
- Inform: "This is a [functional/non-functional] requirement, not a decision."
- Create the appropriate spec file instead (use templates from `_templates/TEMPLATES.md`)
- Suggest: "Use `/blueprint:require` for future requirements."

**If classification is ambiguous** (e.g. a choice that's both technical and UX-facing) **and `design/` exists**:
- Ask the user once: "Is this primarily a tech/architecture decision (engineering reviewers) or a UX decision (design reviewers)?"
- File in the chosen tree.

**If classification is ambiguous and `design/` is missing**: file as ADR. The user can always re-file later by running `/blueprint:onboard-design` and `/blueprint:supersede`.

## Updating DESIGN.md

Use this only for cross-cutting design rules and prohibitions, not per-context rationale.

1. Read existing `DESIGN.md` if present.
2. Add the rule under the nearest existing heading (for example `Visual rules`, `Voice and tone`, `Prohibitions`) or create a concise heading if needed.
3. Keep the edit short: one bullet with the rule and, if the user gave one, a brief reason.
4. Do not add a long template, audit checklist, or per-screen detail.
5. If the rule comes from a UX decision, reference `UX-NNN`; if a later UX decision follows the rule, reference `DESIGN.md` from that UX decision instead of duplicating the text.

## Strong UX Signal Without Tree

If the input clearly looks like a UX decision (e.g. mentions modal vs page, confirmation pattern, navigation, copy/voice, empty state, motion, interaction model) **and** the `design/` tree does NOT exist:

1. **Do NOT silently file as an ADR.** UX rationale in `docs/adrs/` becomes a content classification violation later.
2. **Warn the user, exactly once:**
   ```
   This looks like a UX/design decision, but this repo has no `design/` tree.
   The design tree is opt-in to keep design and engineering review paths separate.

   Options:
   - Run `/blueprint:onboard-design` to set up the design tree, then re-run this command
   - File as ADR anyway (you can move it later with `/blueprint:supersede`)
   - Cancel
   ```
3. Use `AskUserQuestion` to capture the choice.
4. If the user picks "File as ADR anyway": file as ADR with a note in the Context section: `Note: this captures UX rationale but is filed as ADR because no design tree exists. Move with /blueprint:supersede after running /blueprint:onboard-design.`
5. If "Cancel" or no answer: stop and create nothing.

## Input Parsing

| Input | Action |
|-------|--------|
| `/decide PostgreSQL because team knows it` | Create ADR immediately |
| `/decide PostgreSQL` | Ask for r