# Adr Capture

> ALWAYS activate when the student makes a high-level design choice -- library selection, database choice, mathematical approach, architecture pattern, or trade-off decision. Captures an Architectural Decision Record proving leadership-level thinking. Invoke with /adr.

- Skill: `aman-bhandari/adr-capture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aman-bhandari/adr-capture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aman-bhandari/adr-capture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aman-bhandari (https://skillmd.com/u/aman-bhandari)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aman-bhandari/adr-capture

---


# 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:

```markdown
# 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."