/adr

Create an Architecture Decision Record (ADR) when making a non-obvious architectural call. Captures the decision, context, and agent-specific guidance to prevent future agents from undoing intentional choices.

Usage

/adr <title> [--status <status>]

Arguments

• title: Short description of the decision (e.g., "use Prisma over SQLAlchemy")
• --status: Decision status (default: Accepted). Options: Proposed, Accepted, Deprecated

Instructions

When this skill is invoked:

Agent Behavior

Autonomy:

• Gather context from the current session — what was decided and why
• Determine the next ADR number automatically
• Generate the full ADR document without prompting
• Update the index file

Quality:

• Focus on the WHY, not just the WHAT
• The Agent Guidance field is the most important — it tells future agents what to do
• The Do Not Change field prevents accidental refactoring of intentional patterns
• Keep it concise — aim for a document that takes < 2 minutes to read

Process

1. Determine Next ADR Number

ls docs/decisions/[0-9]*.md 2>/dev/null | sort -t/ -k3 -n | tail -1

If no ADRs exist, start at 0001. Otherwise, increment the highest number.

2. Gather Decision Context

From the current session, extract:

• Context: What problem or question led to this decision?
• Options considered: What alternatives were evaluated?
• Decision: What was chosen and why?
• Trade-offs: What are the positive and negative consequences?
• Agent guidance: One sentence telling future agents how to behave
• Do not change: Patterns that must be preserved

If context is unclear, ask the user a maximum of 2 clarifying questions.

3. Create ADR File

Filename: docs/decisions/NNNN-{slug}.md

Use the template from docs/decisions/adr-template.md with all fields filled in.

4. Update Index

Add a row to the table in docs/decisions/index.md:

| NNNN | {Title} | Accepted | YYYY-MM-DD |

5. Present Summary

ADR created: docs/decisions/NNNN-{slug}.md

Decision: {one-line summary}
Agent Guidance: {the agent-guidance field}
Do Not Change: {count} patterns locked

Index updated: docs/decisions/index.md

When to Use This Skill

Use /adr after:

• Choosing one technology/library over another
• Deciding on an architectural pattern (e.g., service layer, event sourcing)
• Making a non-obvious design choice that future developers might question
• Resolving a trade-off where the reasoning matters
• Any decision where you think "a future agent might try to change this"

Don't use for:

• Obvious choices that follow existing project patterns
• Trivial implementation details
• Temporary workarounds (use /compound instead)

Example

$ /adr "use cursor-based pagination over offset"

ADR created: docs/decisions/0001-use-cursor-based-pagination-over-offset.md

Decision: Use cursor-based pagination for all list endpoints
Agent Guidance: Do not convert cursor pagination to offset — cursor was
chosen for consistent ordering under concurrent writes.
Do Not Change: 2 patterns locked

Index updated: docs/decisions/index.md