/architecture-decision

name: architecture-decision
description: "Creates an Architecture Decision Record (ADR) documenting a significant technical decision, its context, alternatives considered, and consequences. Every major technical choice should have an ADR."
argument-hint: "[title] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion
model: sonnet

When this skill is invoked:

0. Parse Arguments — Detect Retrofit Mode

Resolve the review mode (once, store for all gate spawns this run): 1. If `--review [full|lean|solo]` was passed → use that 2. Else read `production/review-mode.txt` → use that value 3. Else → default to `lean`

See `.claude/docs/director-gates.md` for the full check pattern.

**If the argument starts with `retrofit` followed by a file path** (e.g., `/architecture-decision retrofit docs/architecture/adr-0001-event-system.md`):

Enter **retrofit mode**:

1. Read the existing ADR file completely. 2. Identify which template sections are present by scanning headings:

• `## Status` — **BLOCKING if missing**: `/story-readiness` cannot check ADR acceptance
• `## ADR Dependencies` — HIGH if missing: dependency ordering breaks
• `## Engine Compatibility` — HIGH if missing: post-cutoff risk unknown
• `## GDD Requirements Addressed` — MEDIUM if missing: traceability lost

3. Present to the user:

   ## Retrofit: [ADR title]
   File: [path]

   Sections already present (will not be touched):
   ✓ Status: [current value, or "MISSING — will add"]
   ✓ [section]

   Missing sections to add:
   ✗ Status — BLOCKING (stories cannot validate ADR acceptance without this)
   ✗ ADR Dependencies — HIGH
   ✗ Engine Compatibility — HIGH

4. Ask: "Shall I add the [N] missing sections? I will not modify any existing content." 5. If yes:

• For **Status**: ask the user — "What is the current status of this decision?"

Options: "Proposed", "Accepted", "Deprecated", "Superseded by ADR-XXXX"

• For **ADR Dependencies**: ask — "Does this decision depend on any other ADR?

Does it enable or block any other ADR or epic?" Accept "None" for each field.

• For **Engine Compatibility**: read the engine reference docs (same as Step 1 below)

and ask the user to confirm the domain. Then generate the table with verified data.

• For **GDD Requirements Addressed**: ask — "Which GDD systems motivated this decision?

What specific requirement in each GDD does this ADR address?"

• Append each missing section to the ADR file using the Edit tool.
• **Never modify any existing section.** Only append or fill absent sections.

6. After adding all missing sections, update the ADR's `## Date` field if it is absent. 7. Suggest: "Run `/architecture-review` to re-validate coverage now that this ADR has its Status and Dependencies fields."

If NOT in retrofit mode, proceed to Step 1 below (normal ADR authoring).

**No-argument guard**: If no argument was provided (title is empty), ask before running Phase 0:

> "What technical decision are you documenting? Please provide a short title > (e.g., `event-system-architecture`, `physics-engine-choice`)."

Use the user's response as the title, then proceed to Step 1.

---

1. Load Engine Context (ALWAYS FIRST)

Before doing anything else, establish the engine environment:

1. Read `docs/engine-reference/[engine]/VERSION.md` to get:

• Engine name and version
• LLM knowledge cutoff date
• Post-cutoff version risk levels (LOW / MEDIUM / HIGH)

2. Identify the **domain** of this architecture decision from the title or user description. Common domains: Physics, Rendering, UI, Audio, Navigation, Animation, Networking, Core, Input, Scripting.

3. Read the corresponding module reference if it exists: `docs/engine-reference/[engine]/modules/[domain].md`

4. Read `docs/engine-reference/[engine]/breaking-changes.md` — flag any changes in the relevant domain that post-date the LLM's training cutoff.

5. Read `docs/engine-reference/[engine]/deprecated-apis.md` — flag any APIs in the relevant domain that should not be used.

6. **Display a knowledge gap warning** before proceeding if the domain carries MEDIUM or HIGH risk:

   ⚠️  ENGINE KNOWLEDGE GAP WARNING
   Engine: [name + version]
   Domain: [domain]
   Risk Level: HIGH — This version is post-LLM-cutoff.

   Key changes verified from engine-reference docs:
   - [Change 1 relevant to this domain]
   - [Change 2]

   This ADR will be cross-referenced against the engine reference library.
   Proceed with verified information only — do NOT rely solely on training data.

If no engine has been configured yet, prompt: "No engine is configured. Run `/setup-engine` first, or tell me which engine you are using."

---

2. Determine the next ADR number

Scan `docs/architecture/` for existing ADRs to find the next number.

---

3. Gather context

Read related code, existing ADRs, and relevant GDDs from `design/gdd/`.

3a: Architecture Registry Check (BLOCKING gate)

Read `docs/registry/architecture.yaml`. Extract entries relevant to this ADR's domain and decision (grep by system name, domain keyword, or state being touched).

Present any relevant stances to the user **before** the collaborative design begins, as locked constraints:

## Existing Architectural Stances (must not contradict)

State Ownership:
  player_health → owned by health-system (ADR-0001)
  Interface: HealthComponent.current_health (read-only float)
  → If this ADR reads or writes player health, it must use this interface.

Interface Contracts:
  damage_delivery → signal pattern (ADR-0003)
  Signal: damage_dealt(amount, target, is_crit)
  → If this ADR delivers or receives damage events, it must use this signal.

Forbidden Patterns:
  ✗ autoload_singleton_coupling (ADR-0001)
  ✗ direct_cross_system_state_write (ADR-0000)
  → The proposed approach must not use these patterns.

If the user's proposed decision would