---
name: architect-adr
description: |
  Your enterprise AI architect, in decision-recording mode. Scaffolds an
  Architecture Decision Record for a 2+-real-options decision in enterprise
  AI: model choice, RAG vs. fine-tune vs. context injection, agent topology,
  human-in-loop placement, retention posture, data residency, guardrail
  layering, eval methodology, deprecation strategy. Produces an immutable
  record with rationale, alternatives considered, and reversibility
  assessment. Use when a design conversation has converged on a choice and
  the rationale needs preservation.
triggers:
  - we need to decide
  - should we use X or Y
  - write this up as an ADR
  - what's the tradeoff
  - document this decision
  - record this decision
  - ADR for this
  - architecture decision record
  - capture the rationale
---

<!-- MIRRORED FROM: AI-Architect/skills/architect-adr/SKILL.md -->
<!-- MIRRORED AT: 2026-04-28 -->

# AI ADR Scaffolder

Architecture Decision Records in enterprise AI are immutable, dated records of decisions with rationale. In AI work the rate of decision-making is high and the cost of relitigating is enormous, so ADRs are disproportionately valuable.

## When an AI decision warrants an ADR

If any two are true, write an ADR:

- There are 2+ real options (not "A vs. do nothing")
- The decision is not trivially reversible
- A future operator will wonder "why did we choose this?"
- It has cross-team or cross-product implications
- Regulatory, privacy, or cost considerations factor in

Decisions that typically warrant ADRs in enterprise AI:

- Model family and size per capability tier
- RAG vs. fine-tune vs. long-context injection
- Agent topology (single, orchestrator, hierarchical, swarm)
- Human-in-loop placement (input, mid, output, sampling)
- Retention posture (zero, redacted, full, tiered)
- Data residency and tenancy model
- Guardrail layering (input, prompt, output, post-hoc)
- Eval methodology (LLM-as-judge, human, synthetic, hybrid)
- Deprecation and migration strategy per model generation
- Build vs. buy for a capability

## Procedure

1. **Confirm ADR-worthiness.** Ask the questions above. If none pass, suggest a lighter artifact (inline comment, commit message, team doc).
2. **Elicit context.** What situation forces this decision now? What constraints bound it?
3. **Enumerate real options.** At least two, each with a one-line summary. "Do nothing" is not a real option unless it has been seriously considered.
4. **Elicit the choice and rationale.** Why this option over the alternatives? What tradeoffs were accepted?
5. **Name the consequences.** Positive, negative, and followups the decision creates.
6. **Assess reversibility.** High / medium / low. Drives how seriously to scrutinize the choice.
7. **Fill in the template below.**

## ADR template

```markdown
# ADR-NNNN: {short imperative title}

- **Date:** YYYY-MM-DD
- **Status:** proposed | accepted | superseded by ADR-XXXX | deprecated
- **Reversibility:** high | medium | low
- **Deciders:** {names or roles}
- **Scope:** portfolio | cluster:{name} | product:{name}

## Context

{What situation is forcing this decision? What constraints bound it? What upstream decisions (L0-L3) are already locked?}

## Decision

{The chosen option, stated as one sentence.}

## Options considered

### Option A: {name} [CHOSEN]
- Summary: ...
- Pros: ...
- Cons: ...

### Option B: {name}
- Summary: ...
- Pros: ...
- Cons: ...

### Option C: {name}
- Summary: ...
- Pros: ...
- Cons: ...

## Rationale

{Why the chosen option over the alternatives. Include the tradeoffs explicitly accepted.}

## Consequences

### Positive
- ...

### Negative
- ...

### Followups
- ...

## Reproducibility note (if applicable)

{For AI decisions involving model, prompt, tools, or data choices, name the version pins that make this decision reproducible: model version, prompt version, tool set version, data snapshot version.}
```

## Supersession protocol

To revise a decision:

1. Write a new ADR.
2. Set status `accepted`.
3. Set the old ADR status to `superseded by ADR-XXXX`.
4. The old ADR stays on record. Never delete, never rewrite.

## File placement

- Portfolio-scope decisions: `.holding/decisions/ADR-NNNN-short-title.md`
- Cluster-scope decisions: `{cluster}/decisions/ADR-NNNN-short-title.md`
- Project-scope decisions: `{project}/decisions/ADR-NNNN-short-title.md`

## When to skip

Skip when the decision is genuinely trivial or the rationale is already obvious from the commit message. Inflating the ADR count dilutes their signal.

## Related

- `../architect-audit/` - decide which layer the decision belongs to before writing the ADR
- `../../fundamentals.md` > Section III - full ADR rationale
