---
name: apex-azure-adr
user-invocable: true
disable-model-invocation: false
argument-hint: "project and architecture decision"
description: '**ANALYSIS SKILL** — Creates Azure Architecture Decision Records (ADRs) with WAF pillar mapping, alternatives, and consequences. WHEN: "create ADR", "document decision", "architecture decision record", "record why we chose", "WAF pillar justification", "trade-off analysis". DO NOT USE FOR: IaC code (06b/06t agents), diagrams (apex-python-diagrams), cost estimates (cost-estimate-subagent).'
compatibility: Works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool; no external dependencies required.
license: MIT
metadata:
  author: jonathan-vella
  version: "1.0"
  category: document-creation
---

# Azure Architecture Decision Records (ADR) Skill

Create formal Architecture Decision Records that document significant
infrastructure decisions with Azure-specific context, WAF pillar analysis,
and implementation guidance.

## Output Naming

ADRs are saved to `agent-output/{project}/` with one of two phase prefixes:

| Phase              | Prefix          | Status default | Trigger                                      |
| ------------------ | --------------- | -------------- | -------------------------------------------- |
| Step 3 (Design)    | `03-des-adr-`   | `Proposed`     | Architect agent, design/planning language    |
| Step 7 (As-Built)  | `07-ab-adr-`    | `Accepted`     | After deploy, implemented/current-state language |

Full filename: `{prefix}NNNN-{kebab-title}.md` (e.g.,
`03-des-adr-0001-use-cosmos-db-for-state.md`). NNNN is 4-digit sequential
per project.

The `07-ab-adr-` ADR may differ from `03-des-adr-` if implementation
required changes — document deviations in the "Implementation Notes"
section.

## Rules

1. **One decision per ADR** — keep ADRs focused on a single decision
2. **Include alternatives** — always document at least 2-3 considered and rejected
3. **Map to WAF pillars** — show impact on each of the 5 Well-Architected pillars
4. **Link to requirements** — reference the requirement that drove the decision
5. **Keep it concise** — ADRs should be readable in 5 minutes
6. **Document both consequences** — at least 1 positive and 1 negative

## Steps

1. **Gather context** — decision context, alternatives, stakeholders
2. **Determine number** — check existing ADRs in `agent-output/{project}/` for next sequence
3. **Determine phase** — design (`03-des-`) or as-built (`07-ab-`)
4. **Generate document** — follow [`references/adr-template.md`](references/adr-template.md)
5. **Include WAF analysis** — map decision impact to all 5 pillars
6. **Document alternatives** — list 2-3 with rejection reasons
7. **Self-check** — run through [`references/quality-checklist.md`](references/quality-checklist.md)

## Reference Index

Load on demand:

| Reference                          | When to Load                                          |
| ---------------------------------- | ----------------------------------------------------- |
| `references/adr-template.md`       | Authoring the ADR (full template with all sections)   |
| `references/example-prompts.md`    | Looking for trigger phrasing / common ADR topics      |
| `references/quality-checklist.md`  | Final self-check before saving                        |
| `references/guardrails.md`         | DO/DON'T rules, anti-pattern table                    |