gh-mgiovani-cc-arsenal/commands/docs/adr.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Create numbered ADR documenting architectural decision	<title> [variant]	Read Write Grep Glob

Create Architecture Decision Record

Create a new Architecture Decision Record (ADR) documenting an architectural decision.

Your Task

1. Parse Arguments:

   • Extract decision title from $ARGUMENTS
   • Check for variant keyword: lightweight, full, or madr
   • If variant found, remove it from title
   • Default variant: nygard (Nygard style)

2. Determine ADR Number:

   • Scan docs/adr/ directory
   • Find highest existing ADR number (format: XXXX-*)
   • Increment by 1
   • If no ADRs exist, start with 0001
   • Format as 4-digit padded number (e.g., 0001, 0023)

3. Sanitize Title for Filename:

   • Convert title to kebab-case
   • Remove special characters
   • Lowercase all letters
   • Example: "Use Redis for Caching" → use-redis-for-caching

4. Gather Context:

   • Search codebase for relevant information about the decision topic
   • Look for related code, configs, or documentation
   • Understand current state and alternatives
   • Keep context concise but informative

5. Load Template:

   • Template location: commands/docs/templates/adr/
   • Select based on variant:
     • nygard → nygard.md (default)
     • lightweight → lightweight.md
     • full → full.md
     • madr → madr.md

6. Populate Template: Replace placeholders:

   • {{ADR_NUMBER}} - 4-digit number
   • {{ADR_TITLE}} - Original title (Title Case)
   • {{DATE}} - Current date (YYYY-MM-DD)
   • {{CONTEXT}} - Gathered context from codebase
   • {{PROJECT_NAME}} - Git repo or directory name

7. Create ADR File:

   • Filename: docs/adr/XXXX-kebab-case-title.md
   • Ensure docs/adr/ directory exists
   • Write populated content
   • Set initial status to "Proposed"

8. Report Creation:

   • Show ADR number and title
   • Display file path
   • Provide next steps

Template Variants

Nygard Style (Default)

Michael Nygard's ADR format - concise and focused.

Sections:

• Title with number
• Status
• Context
• Decision
• Consequences

Use when: Most decisions, balanced detail

Lightweight

Minimal ADR for quick decisions.

Sections:

• Title with number
• Status
• Decision
• Rationale

Use when: Simple, straightforward decisions

Full

Comprehensive ADR with detailed sections.

Sections:

• Title with number
• Status
• Context
• Decision Drivers
• Considered Options
• Decision
• Consequences (Positive, Negative, Neutral)
• Pros and Cons
• Related Decisions
• References

Use when: Complex, high-impact decisions

MADR

Markdown Architectural Decision Records format.

Sections:

• Title with number
• Status
• Context and Problem Statement
• Decision Drivers
• Considered Options
• Decision Outcome
• Consequences

Use when: Following MADR standard

Usage

Basic ADR creation (uses Nygard template):

/docs:adr "Database Migration Strategy"
/docs:adr "API Authentication Approach"
/docs:adr "Microservices Communication Pattern"

With template variant override:

/docs:adr lightweight "Use Redis for Session Storage"
/docs:adr full "Adopt Event-Driven Architecture"
/docs:adr madr "Select Database Technology"

ADR Numbering

• First ADR: 0001-record-architecture-decisions.md (meta-ADR)
• Subsequent ADRs: Auto-incremented (0002, 0003, etc.)
• Format: XXXX-kebab-case-title.md

ADR Status Lifecycle

Update status in the ADR as the decision progresses:

1. Proposed - Initial proposal (default)
2. Accepted - Decision approved
3. Deprecated - No longer recommended
4. Superseded - Replaced by another ADR

Context Gathering Examples

# For database decisions
!`find . -name "*.sql" -o -name "*models.py" -o -name "*schema.prisma" | head -10`

# For API decisions
!`grep -r "router\|endpoint\|api" --include="*.py" --include="*.ts" --include="*.js" . | head -20`

# For architecture decisions
!`find . -name "docker-compose.yml" -o -name "*.config.js" -o -name "*.config.ts" | head -10`

Important Notes

• One Decision per ADR: Keep focused on a single decision
• Context Matters: Include "why" even if it seems obvious
• Link Related ADRs: Reference superseded or related decisions
• Early Documentation: Create ADRs early in decision process
• Imperative Language: Use "we will" not "we should"
• Status Updates: Update status as decision progresses

Example Output

Architecture Decision Record Created ✓

ADR-0006: Use Redis for Session Storage
File: docs/adr/0006-use-redis-for-session-storage.md
Status: Proposed
Template: Nygard Style

Next Steps:
  1. Review and refine the decision context
  2. Fill in consequences (positive/negative)
  3. Discuss with team
  4. Update status to "Accepted" when approved
  5. Reference this ADR in related code/docs

When to Create ADRs

Create an ADR when making:

• Technology stack decisions
• Architecture pattern choices
• Database or storage decisions
• API design choices
• Security architecture decisions
• Deployment strategy decisions
• Major library/framework selections
• Cross-cutting concerns (logging, caching, etc.)

Best Practices

• Create early: Document decisions before implementation
• Be honest: Document the real reasons, not ideal reasons
• Include alternatives: Show what was considered
• Accept trade-offs: Acknowledge negative consequences
• Link to code: Reference implementation in the ADR
• Review regularly: Revisit ADRs during retrospectives
• Update status: Keep status current as decisions evolve

---

Template Location: commands/docs/templates/adr/ Output Directory: docs/adr/