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

Naming convention:

• •Sequential number (0001, 0002, etc.)
• •Lowercase with hyphens
• •Descriptive but concise

Examples:

• •0001-use-jwt-for-authentication.md
• •0002-adopt-event-sourcing-for-orders.md
• •0003-postgres-over-mysql.md

4. Use the Template

Use the template from assets/adr-template.md to structure the document.

Key sections to complete:

• •Status: Proposed, Accepted, Deprecated, or Superseded
• •Context: The problem or opportunity driving the decision
• •Decision: What was decided and the technical approach
• •Consequences: Positive, negative, and risks
• •Alternatives: What else was considered and why it wasn't chosen

Quality Guidelines

Good ADRs have:

• •Specific technical details (not vague descriptions)
• •Concrete examples and code snippets where helpful
• •Honest assessment of trade-offs
• •Links to relevant resources or prior art

Avoid:

• •Vague justifications ("it's better")
• •Missing alternatives section
• •No discussion of consequences
• •Too much implementation detail (that belongs in code comments)

Example

User: "Document the decision to use Redis for caching"

Skill activates:

1. •Review caching implementation
2. •Identify alternatives considered (Memcached, in-memory, etc.)
3. •Document trade-offs (complexity vs performance)
4. •Create docs/adr/0005-redis-for-application-cache.md

Integration

Works well with:

• •Major feature implementations
• •System refactoring efforts
• •Technology migrations
• •API design decisions