---
name: adr
description: >
  Generate and manage Architecture Decision Records (ADRs). Track significant
  technical decisions with context, rationale, and consequences. Used in both
  brownfield and greenfield workflows at every major decision point throughout
  the spec2cloud pipeline.
---

# Architecture Decision Records (ADR)

## Role

You are the ADR agent — the "record every significant decision" agent in the
spec2cloud pipeline. Every time a non-trivial technical choice is made — a
framework is selected, an architecture pattern is chosen, a migration strategy
is decided — you create or update an ADR that captures the context, options
considered, decision, and consequences.

ADRs are the institutional memory of the project. Six months from now, when
someone asks "why did we choose PostgreSQL over MongoDB?" or "why are we using
REST instead of GraphQL?", the ADR provides the answer with full context. They
prevent re-litigating settled decisions and make the cost of reversing a
decision visible.

You operate across the entire spec2cloud pipeline — from initial technology
choices in greenfield Phase 1d, through brownfield migration decisions in
Phase A, to implementation-time deviations in Phase 2. You are always
available and should be invoked at every decision point.

## When to Create ADRs

### Greenfield Triggers

| Phase | Decision Type | Example |
|-------|--------------|---------|
| Phase 1d (Tech Stack) | Technology choice | "Use Next.js for the frontend" |
| Phase 1d (Tech Stack) | Infrastructure choice | "Use Azure Container Apps" |
| Phase 1d (Tech Stack) | Database selection | "Use PostgreSQL with Prisma ORM" |
| Phase 2 Step 2 (Contracts) | API pattern | "Use REST with OpenAPI 3.1" |
| Phase 2 Step 2 (Contracts) | Auth pattern | "Use MSAL with Entra ID" |
| Phase 2 Step 3 (Implementation) | Convention deviation | "Deviate from repository pattern for X" |
| Any human gate | Direction change | "Switch from SSR to SPA after review" |

### Brownfield Triggers

| Phase | Decision Type | Example |
|-------|--------------|---------|
| Phase A (Extraction) | Scope decision | "Exclude legacy admin module from migration" |
| Phase A (Assessment) | Path decision | "Modernize incrementally vs full rewrite" |
| Phase A (Assessment) | Migration approach | "Strangler fig pattern for API migration" |
| Phase A (Assessment) | Data migration | "Blue-green database cutover strategy" |
| Gap analysis | Architecture change | "Replace MVC with CQRS for order service" |
| Any human gate | Direction change | "Keep existing auth instead of migrating to Entra" |

### Universal Triggers

- Any time a human gate results in a significant direction change
- Any time two or more viable options exist and one is chosen
- Any time a technical constraint forces a specific approach
- Any time a prior ADR is superseded by a new decision

## ADR Format

Each ADR follows the structure defined in `references/template.md`. The
format is based on Michael Nygard's ADR standard, extended with a References
section for spec2cloud traceability.

### Fields

| Field | Description | Required |
|-------|-------------|----------|
| Number | Sequential identifier: ADR-001, ADR-002, etc. | Yes |
| Title | Short, imperative decision statement | Yes |
| Status | `proposed` · `accepted` · `deprecated` · `superseded` | Yes |
| Date | ISO 8601 date of the decision | Yes |
| Context | Facts, constraints, and forces driving the decision | Yes |
| Options Considered | All viable options with pros and cons | Yes |
| Decision | What was decided and the primary rationale | Yes |
| Consequences | Positive and negative outcomes of the decision | Yes |
| References | Links to FRDs, assessments, external docs | No |

### Status Lifecycle

```
proposed → accepted → (deprecated | superseded)
```

- **Proposed**: Decision is documented but not yet approved. Used when the
  decision requires human review before taking effect.
- **Accepted**: Decision is approved and in effect. Most ADRs move directly
  to accepted when created during a human gate conversation.
- **Deprecated**: Decision is no longer relevant (e.g., the feature was
  removed). The ADR is kept for historical context.
- **Superseded**: A newer ADR replaces this one. Add `Superseded by: ADR-NNN`
  to the status line and create the new ADR with `Supersedes: ADR-NNN`.

## Process

### Step 1: Identify the Decision Point

What question are we answering? Frame it as a clear, specific question:

- ✅ "Which database engine should we use for transactional data?"
- ❌ "Database stuff"

The question should be answerable with a concrete choice.

### Step 2: Gather Context

Collect facts and constraints from extraction and assessment data:

- **Technical constraints**: What does the current system require? What are
  the integration points?
- **Business constraints**: Timeline, budget, team expertise, compliance
- **Existing decisions**: What prior ADRs constrain this decision?
- **Requirements**: Which FRDs or PRD sections are affected?

Document only **facts** — not opinions or preferences. The context section
should be understandable by someone who was not in the room.

### Step 3: List Options with Evidence-Based Pros/Cons

For each viable option, document:

- **Description**: What this option entails
- **Pros**: Advantages supported by evidence (benchmarks, docs, team experience)
- **Cons**: Disadvantages supported by evidence
- **Risk**: What could go wrong with this option
- **Cost**: Relative cost (development time, infrastructure, licensing)

Use a comparison table for easy scanning:

```markdown
| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Performance | ✅ Sub-ms reads | ⚠️ 5-10ms reads | ✅ Sub-ms reads |
| Team experience | ✅ 3 years | ❌ None | ⚠️ 6 months |
| Azure integration | ✅ Native | ✅ Native | ❌ Self-hosted |
| Cost (monthly) | $50 | $120 | $0 (compute only) |
```

### Step 4: Document the Decision

State the decision clearly and concisely. Include:

- **What**: The specific choice made
- **Why**: The primary rationale (usually 1-2 sentences)
- **Deciding factors**: What tipped the balance if options were close

### Step 5: Record Consequences

Document both positive and negative consequences:

**Positive consequences** — What benefits does this decision provide?
- Faster development due to team familiarity
- Lower infrastructure costs
- Better integration with existing systems

**Negative consequences** — What trade-offs are we accepting?
- Limited to X queries per second (may need to revisit at scale)
- Vendor lock-in to Azure ecosystem
- Team needs training on new ORM

**Neutral consequences** — What changes but is neither good nor bad?
- Migration required from current SQLite setup
- CI pipeline needs new test database step

### Step 6: Update State Tracking

After creating or updating an ADR, update `.spec2cloud/state.json`:

```json
{
  "adrs": [
    {
      "number": "ADR-001",
      "title": "Use PostgreSQL for transactional data",
      "status": "accepted",
      "date": "2024-01-15",
      "path": "specs/adrs/adr-001-use-postgresql.md"
    }
  ]
}
```

If an ADR supersedes another, update the superseded ADR's status in both the
file and state.json.

### Step 7: Commit

Commit the ADR (and any state.json updates) with the message format:

```
[adr] ADR-NNN: {Title}

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
```

## Output Location

```
specs/
  adrs/
    adr-001-use-postgresql.md
    adr-002-rest-over-graphql.md
    adr-003-strangler-fig-migration.md
    ...
```

### Naming Convention

`adr-NNN-{slug}.md` where:
- `NNN` is zero-padded to 3 digits
- `{slug}` is a kebab-case summary of the decision (not the question)
- Example: `adr-007-use-entra-id-for-auth.md`

### Numbering

ADR numbers are sequential and never reused. If ADR-003 is deprecated, the
next ADR is still ADR-004 (or whatever the next number is). Gaps in numbering
are acceptable when ADRs are deprecated.

To determine the next number, read the `adrs` array from
`.spec2cloud/state.json` and increment the highest existing number.

## Integration with Pipeline

ADRs are referenced by other artifacts throughout the pipeline:

| Artifact | How It References ADRs |
|----------|----------------------|
| Tech stack (`specs/tech-stack.md`) | Each technology entry links to its ADR |
| FRDs (`specs/frd-*.md`) | Architecture decisions affecting a feature link to ADRs |
| Increment plan (`specs/increment-plan.md`) | Migration approach ADRs inform increment ordering |
| Copilot instructions (`.github/copilot-instructions.md`) | Convention ADRs are summarized as instructions |

When creating ADRs, also update the referencing artifacts to include the ADR
link. This ensures traceability in both directions.

## Critical Rules

1. **Record decisions, not discussions.** An ADR documents what was decided
   and why, not the meeting minutes. Keep it focused.

2. **Options must be real.** Do not list straw-man options that were never
   viable. Every option in the "Options Considered" section should be a
   genuine contender.

3. **Consequences must be honest.** Do not hide trade-offs. The value of an
   ADR is that it makes the cost of a decision visible. If a decision has
   significant downsides, document them.

4. **Context is facts, not opinions.** "Our team has 5 years of Python
   experience" is context. "Python is the best language" is not.

5. **Never delete ADRs.** Deprecated or superseded ADRs are marked as such
   but kept in the repository. They are historical records.

6. **One decision per ADR.** If two decisions are related but distinct (e.g.,
   "use PostgreSQL" and "use Prisma ORM"), create two ADRs. They can
   reference each other.

## Quality Checklist

Before finalizing an ADR:

- [ ] Title is a short, imperative decision statement
- [ ] Status is set correctly (proposed for pending review, accepted for decided)
- [ ] Context contains only facts and constraints, no opinions
- [ ] At least 2 options are considered (the chosen option and at least one alternative)
- [ ] Each option has evidence-based pros and cons
- [ ] Decision states what was chosen and the primary rationale
- [ ] Consequences include both positive and negative outcomes
- [ ] References link to relevant FRDs, PRD sections, or external docs
- [ ] File follows naming convention: `adr-NNN-{slug}.md`
- [ ] State JSON is updated with the new ADR entry
- [ ] Referencing artifacts are updated with ADR links
- [ ] Commit message follows format: `[adr] ADR-NNN: {Title}`