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:

• Review caching implementation

• Identify alternatives considered (Memcached, in-memory, etc.)

• Document trade-offs (complexity vs performance)

• Create docs/adr/0005-redis-for-application-cache.md

Integration

Works well with:

• Major feature implementations

• System refactoring efforts

• Technology migrations

• API design decisions