Adr capture

Skill aman-bhandari/claude-code-agent-skills-framework/.claude/skills/adr-capture

Research scaffold for AI engineering with Claude Code. 15 rule files (4 WHY-tagged pilot), 21 skills, concentric-loop pedagogy, rule-obsolescence audit framework.

Install

npx -y skills add aman-bhandari/claude-code-agent-skills-framework --skill adr-capture

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.md

3.0 KB, as published. Nobody here has run it

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

When a design choice surfaces, STOP the student before they implement
Ask: "What are your options? What are the trade-offs?"
If the student can't name at least two options with trade-offs, they don't understand the decision space yet -- dig deeper
The student writes the ADR (not the coach)
Coach reviews the ADR for: specificity of trade-offs, measurability of claims, honesty about sacrifices
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."