/architecture-decision

name: architecture-decision
description: "Create an ADR documenting a technical decision: context, alternatives considered, consequences."
argument-hint: "[title | retrofit <path> | accept <ADR-id>] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(wc -c *), Bash(bash "*/.claude/skills/architecture-decision/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/registry.sh *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,team.size`

Resolved above — use as-is; `--review` overrides `review_mode`. No block → defaults in `.claude/docs/config-resolution.md`.

Architecture Decision

When this skill is invoked:

0. Parse Arguments — Detect Retrofit / Acceptance Mode

See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.

Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

**`team.size`**: which agents validate this ADR (orthogonal to review_mode/workflow).

• **`individual`** (default): `technical-director` (TD-ADR) + the engine-specialist.
• **`small`** and **`studio`**: the same two. This skill spawns no engine

sub-specialist and no adversarial reviewer at any size.

**`docs.density`** — it controls the *depth* of the ADR's prose sections, not which sections the skeleton emits (that is fixed). `modes.rigor` sets it alongside `workflow`; set `docs.density` explicitly to vary ADR verbosity alone: `terse` (the default, via `rigor: minimal`) = decision + alternatives as bullets, one line of rationale each; `balanced` = paragraph per section with light rationale (`rigor: standard`); `thorough` = full prose with trade-offs and worked rationale in Decision, Alternatives, and Consequences. Apply it to the prose sections; the Engine Compatibility, ADR Dependencies, and GDD Requirements tables are structural and stay whole at every density.

**`workflow`** (see `.claude/docs/workflow-modes.md`):

• `full` — all ADRs on the required ADR list must be completed.
• `standard` — critical ADRs only (Foundation-layer systems).
• `minimal` — not required. Can still be run voluntarily.

**If the argument starts with `retrofit` followed by a file path**

**Read `references/0-retrofit.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.

**If the argument starts with `accept` followed by an ADR id**

**Read `references/0-accept.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.

If NOT in retrofit or acceptance 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)

**Read `references/1-engine-context.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.

2. Determine the next ADR number

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

---

3. Gather context

**Read `references/3-gather-context.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.

4. Guide the decision collaboratively

**Read `references/4-decide.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.

5. Generate the ADR

**Read `references/5-generate.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.

6. Closing Next Steps

After the ADR is written (and registry optionally updated), close with `AskUserQuestion`.

Before generating the widget: 1. Read the `## Required ADRs` section of `docs/architecture/architecture.md` (by section) and list `docs/architecture/adr-*.md`: a required ADR with no file is still unwritten. Without `architecture.md`, look for ADRs flagged in technical-preferences.md or systems-index.md as prerequisites 2. Check if all prerequisite ADRs are now written. If yes, include a "Start writing GDDs" option. 3. List ALL remaining priority ADRs as individual options — not just the next one or two.

Widget format:

ADR-[NNNN] written and registry updated. What would you like to do next?
[1] Write [next-priority-adr-name] — [brief description from prerequisites list]
[2] Write [another-priority-adr] — [brief description]  (include ALL remaining ones)
[N] Start writing GDDs — run `/design-system [first-undesigned-system]` (only show if all prerequisite ADRs are written)
[N+1] Stop here for this session

If there are no remaining priority ADRs and no undesigned GDD systems, offer only "Stop here" and suggest running `/architecture-review` in a fresh session.

**Always include this fixed notice in the closing output (do NOT omit it):**

> To validate ADR coverage against your GDDs, open a **fresh Claude Code session** > and run `/architecture-review`. > > **Never run `/architecture-review` in the same session as `/architecture-decision`.** > The reviewing agent must be independent of the authoring context to give an unbiased > assessment. Running it here would