Architectural Decision Record (ADR) Capture

When This Fires

Automatically when the student makes or discusses:

• Choice of library, framework, or tool
• Database or storage decision
• Mathematical approach selection
• Architecture pattern decision
• Any trade-off where two valid options exist

Also manually via /adr.

The Mandatory ADR Format

Every ADR is written to decisions/ADR-NNN-title.md with this structure:

# ADR-NNN: [The Decision]

**Date:** YYYY-MM-DD
**Status:** Accepted | Superseded by ADR-NNN | Deprecated
**Topic:** [Which curriculum topic this relates to]

## Context

What is the technical constraint or problem that forced this decision? What were we trying to solve? What are the forces at play (performance, cost, complexity, maintainability, learning curve)?

## Options Considered

### Option A: [Name]
- Pros: [specific, measurable]
- Cons: [specific, measurable]
- Cost: [time, compute, complexity]

### Option B: [Name]
- Pros: [specific, measurable]
- Cons: [specific, measurable]
- Cost: [time, compute, complexity]

### Option C: [Name] (if applicable)

## Decision

What was chosen and WHY. Not "we chose X because it's popular" but "we chose X because [specific technical reason] given our constraint of [specific constraint]."

## Trade-offs

What did we sacrifice for what gain? Be explicit:
- Sacrificed: [Latency? Cost? Complexity? Flexibility?]
- Gained: [Performance? Simplicity? Maintainability? Learning value?]

## Verification

How did tests/benchmarks prove this was the right choice? Reference specific test files, benchmark results, or measured outcomes.

## Consequences

What does this decision make easier? What does it make harder? What future decisions does it constrain or enable?

Coach Protocol

1. When a design choice surfaces, STOP the student before they implement
2. Ask: "What are your options? What are the trade-offs?"
3. If the student can't name at least two options with trade-offs, they don't understand the decision space yet -- dig deeper
4. The student writes the ADR (not the coach)
5. Coach reviews the ADR for: specificity of trade-offs, measurability of claims, honesty about sacrifices
6. ADR must be committed alongside the implementation

Why This Matters

ADRs prove leadership thinking. A junior picks a tool. A lead documents WHY they picked it, what they sacrificed, and how they verified the choice. In 18 months, the decisions/ directory is a searchable record of engineering judgment that no interview question can replicate.

Portfolio Impact

Recruiters see: "This person doesn't just build. They make deliberate, documented trade-off decisions with measurable verification. This is how Staff engineers think."