create-adr

name	create-adr
description	Create Architecture Decision Records (ADRs) to document significant technical decisions, their context, alternatives considered, and consequences. Use when making architectural choices, selecting libraries/frameworks, or designing system components.

Create ADR Skill

Purpose: Document architectural decisions to provide context for future developers and maintain institutional knowledge about why technical choices were made.

When to Use This Skill

Trigger this skill when:

• Making significant architectural decisions
• Choosing between competing technologies or approaches
• Designing new system components or APIs
• Refactoring that changes system structure
• After implementing a feature that involved design trade-offs

Skip ADR Creation If

• Only minor bug fixes or refactoring
• Documentation or test-only changes
• Configuration tweaks without architectural impact
• Trivial changes with obvious implementation

Workflow

1. Gather Context

Review the implementation to understand:

• What technical decisions were made
• Why this approach was chosen
• What alternatives existed
• What trade-offs were accepted

If reviewing existing code:

git diff main...HEAD
git log --oneline main..HEAD

2. Investigate Further

If the diff doesn't provide enough context:

• Read referenced files/functions
• Check configuration files
• Review related tests
• Look at dependencies added

3. Create the ADR

Location: docs/adr/NNNN-descriptive-title.md