FAI Architecture Decision Record

Produces MADR (Markdown Architectural Decision Record) format ADRs that capture the full decision context, considered options, and trade-offs. Prevents knowledge rot — the silent killer where teams six months later cannot explain why the architecture looks the way it does.

When to Invoke

MADR Template

# ADR-{NUMBER}: {Title}

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-{N}
**Date:** {YYYY-MM-DD}
**Deciders:** {names or team}
**Tags:** infrastructure, ai, security, cost, performance

## Context and Problem Statement

{One paragraph: what situation forced this decision? What constraint or requirement is in tension?}

## Decision Drivers

- {Primary constraint or goal}
- {Secondary constraint or goal}
- {Quality attribute being optimised: latency, cost, security}

## Considered Options

| Option | Description |
|--------|-------------|
| A | {Name} -- {one-line description} |
| B | {Name} -- {one-line description} |
| C | {Name} -- {one-line description} |

## Decision Outcome

**Chosen option: {A/B/C}**, because {rationale -- which decision drivers it satisfies best}.

### Positive Consequences
- {What improves or becomes possible}

### Negative Consequences
- {What gets harder, more expensive, or more risky}

## Pros and Cons of the Options

### Option A -- {Name}
- Pro: {advantage}
- Con: {disadvantage}

### Option B -- {Name}
- Pro: {advantage}
- Con: {disadvantage}

## Links
- Supersedes: ADR-{N} (if applicable)
- Related: ADR-{N} (if applicable)
- Implementation: {PR or commit link}

Example: Choosing a Vector Search Service

# ADR-007: Vector Search -- Azure AI Search vs Dedicated Vector DB

**Status:** Accepted
**Date:** 2025-04-10
**Deciders:** Platform Team
**Tags:** infrastructure, ai, cost

## Context and Problem Statement

Play 01 (Enterprise RAG) requires a vector store that supports hybrid search,
semantic ranking, and RBAC -- integrated with the existing Azure landing zone.
Latency budget: <200ms at P99 for top-5 retrieval.

## Decision Drivers

- Managed Identity integration with Azure (no secrets)
- Hybrid BM25 + vector recall >= pure vector
- Single Azure bill (no additional vendor)

## Considered Options

| Option | Description |
|--------|-------------|
| A | Azure AI Search -- Azure-native, hybrid, semantic ranker |
| B | Pinecone -- Managed vector DB, REST API |
| C | pgvector -- Self-hosted in PostgreSQL Flexible Server |

## Decision Outcome

**Chosen option: A**, because it satisfies Managed Identity, hybrid search,
and billing consolidation with no additional infrastructure.

### Positive Consequences
- Zero credential management -- Managed Identity to AI Search
- Semantic ranker reduces chunk hallucination

### Negative Consequences
- Vendor lock-in to Azure ecosystem
- Semantic ranker adds ~30ms median latency

ADR File Naming and Storage

# Convention: docs/adr/NNNN-kebab-title.md
docs/adr/
  0001-use-azure-ai-search-for-rag.md
  0002-managed-identity-over-api-keys.md
  0007-vector-search-azure-ai-search-vs-pinecone.md

# Status lifecycle transitions:
# Proposed -> Accepted (after team review)
# Accepted -> Deprecated (feature retired)
# Accepted -> Superseded by ADR-0012 (replaced decision)

Multi-ADR Consistency Check

import re
from pathlib import Path

def check_adr_consistency(adr_dir: str = "docs/adr") -> list[str]:
    """Flag ADRs that reference non-existent superseding ADRs."""
    issues = []
    adrs = {p.stem: p.read_text() for p in Path(adr_dir).glob("*.md")}
    for name, content in adrs.items():
        refs = re.findall(r"Superseded by ADR-(\d+)", content)
        for ref_num in refs:
            target = next((k for k in adrs if k.startswith(ref_num.zfill(4))), None)
            if target is None:
                issues.append(f"{name}: references non-existent ADR-{ref_num}")
    return issues

if __name__ == "__main__":
    problems = check_adr_consistency()
    for p in problems:
        print(f"  WARN: {p}")
    print(f"ADR consistency: {len(problems)} issue(s) found")

ADR Review Workflow

# Propose a new ADR
cp docs/adr/TEMPLATE.md docs/adr/0008-choose-orchestration-framework.md
# Edit, set Status: Proposed, open PR

# Accept after team review
sed -i 's/Status: Proposed/Status: Accepted/' docs/adr/0008-*.md
git commit -m "docs: accept ADR-0008 -- LangChain for RAG orchestration"

# Supersede when a decision changes
sed -i 's/Status: Accepted/Status: Superseded by ADR-0015/' docs/adr/0008-*.md

WAF Alignment

Compatible Solution Plays

• Play 02 — AI Landing Zone (infrastructure decisions)
• Play 01 — Enterprise RAG (retrieval strategy decisions)
• All plays — applicable as a cross-cutting documentation pattern

Notes

• Start numbering at 0001 and zero-pad to 4 digits for sort-friendly file names
• Update the Status field in-place; do not create amendment ADRs
• ADRs are immutable records -- never delete; use Superseded status instead
• The check_adr_consistency script can run in CI to catch broken references