architecture-decision skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation,workflow,docs.density,team.size

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

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; automationalwaysask categories always prompt).

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

Any non-core agent needed at individual routes through the nearest active core agent with a note.

• individual (default): technical-director + lead-programmer + the engine-specialist.
• small: + an engine sub-specialist where applicable.
• studio: + an adversarial review by an alternate engine-specialist.

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 = decision + alternatives as bullets, one line of rationale each; balanced = paragraph per section with light rationale (default); 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 (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

1. 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

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

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

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

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

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

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

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

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

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

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

has its Status and Dependencies fields."

1. After adding all missing sections, update the ADR's ## Date field if it is absent.
2. Suggest: "Run /architecture-review to re-validate coverage now that this ADR

If the argument starts with accept followed by an ADR id (e.g., /architecture-decision accept ADR-0005):

Enter acceptance mode. This is the only path in the framework that moves an ADR from Proposed to Accepted. Authoring always produces Proposed (Step 5), while /create-control-manifest, /create-epics, /create-stories and /gate-check all require Accepted — so without this mode the pipeline had a state it could enter and never leave.

docs/architecture/adr-NNNN-.md for the given number. If no file matches, or more than one** does, stop and say which — do not pick one. If the file has no ## Status section, stop and say so; a missing Status is exactly what retrofit mode is for.

1. Resolve the id to a file, then read it. Glob

If it is Deprecated or Superseded, refuse: reviving a superseded decision is a new ADR, not a status edit.

1. Check the current status. If it is already Accepted, say so and stop.

1. Check its dependencies first. Read ## ADR Dependencies.

If that section is absent, empty, or reads UNKNOWN, do not read it as "no dependencies" — refuse and say which:

"ADR-0005's dependency section is [absent / UNKNOWN], so I cannot tell what

this decision rests on. An empty dependency list and an unexamined one look

identical here, and only one of them is safe to accept. Run

/architecture-decision retrofit to establish it."

A dependency check reading a field that defaults to empty is the vacuous-pass shape this gate exists to prevent — the check would examine nothing and report clean.

If it depends on any ADR that is not itself Accepted, refuse and name them:

"ADR-0005 depends on ADR-0002, which is still Proposed. Accept ADR-0002

first — an accepted decision resting on an unaccepted one is not a decision,

it is a deferral with a different label."

This is the same dependency rule /architecture-review already flags; here it is enforced rather than reported.

the user, or technical-director on the user's explicit confirmation — no other agent, and never this skill on its own. Use AskUserQuestion:

1. Confirm with the user, always. Per CONTRACT.md, acceptance authority is

that depend on it."

• Prompt: "Accept ADR-NNNN — [title]? This is what unblocks stories and epics

This prompt fires regardless of modes.automation, including autonomous. Acceptance is the decision the whole architecture pipeline gates on; it is not a step to be inferred.

• Options: [A] Yes — accept it / [B] Not yet — leave it Proposed

production/epics/[epic-slug]/story-.md — the one place stories live — for files containing both** Status: Blocked and this ADR's id.

1. Find the stories this will unblock, BEFORE the prompt in step 4. Grep

Stories live only under production/epics/. A flat top-level stories

directory does not exist and no skill creates one — never write or match a

path outside production/epics/. /dev-story matches entries *by file

path*, so a story recorded under any other path silently fails to match and