skill-issues: Skill for Claude Code

ADR Skill (Architecture Decision Records)

Lightweight decision records for capturing significant technical decisions with their context and reasoning.

Portable: Copy this skill directory to any repo. Configure location and format in CLAUDE.md.

First-Time Setup

On first use in a repo, confirm with the user:

1. Storage location - Default: decisions/

   • Alternatives: docs/adr/, docs/decisions/

2. File naming - Default: NNN-short-name.md (e.g., 001-auth-approach.md)

3. Additional frontmatter - Some repos require specific frontmatter (tags, authors, etc.)

Once confirmed, document the choices in CLAUDE.md under a "Design Decisions" or "ADRs" section.

When to Create an ADR

Create a decision record when:

• Multiple valid approaches exist with meaningful trade-offs
• Cross-cutting concerns affect multiple parts of the codebase
• The decision needs future reference (why did we choose X?)
• Stakeholder alignment is needed before implementation

Don't create ADRs for:

• Obvious implementation choices
• Decisions that won't matter in a month
• Pure style/formatting preferences

Rule of thumb: If you'd want to explain "why we did it this way" to a future contributor, write an ADR.

Lifecycle

Draft → Accepted → [Superseded by NNN]

• Draft: Under discussion, content may change
• Accepted: Decision made, document is stable (don't edit substance)
• Superseded: Replaced by a newer ADR (link to it)

No "Rejected" status - if you decide against something, either don't write an ADR or mark it Accepted with the decision being "we won't do X because..."

Recommended Structure

# ADR NNN: Title

**Status:** Draft | Accepted | Superseded by NNN
**Date:** YYYY-MM-DD

## Context

What situation or problem prompted this decision? Include relevant constraints.

## Decision

What was decided? Be specific and concrete.

## Consequences

What are the implications? Include both positive and negative.

## Alternatives Considered

What other options were evaluated? Why were they rejected?