DevTrail ADR Skill

Create an Architecture Decision Record (ADR) for significant architectural decisions.

Note: ADRs created by AI agents are marked as

draft

and

review_required: true

by default.

Instructions

Use this skill for major architectural decisions that affect the system structure, technology stack, or design patterns.

1. Gather Context

# Get current date
date +%Y-%m-%d

# Get recent changes for context
git diff --stat HEAD~1 2>/dev/null || git diff --stat

# Check for related ADRs
ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5

2. Confirm with User

Always confirm before creating:

╔══════════════════════════════════════════════════════════════════╗
║  DevTrail ADR                                                    ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                   ║
║  ⚠️  ADRs require human review after creation.                    ║
║                                                                   ║
║  📋 An ADR documents architectural decisions that affect:         ║
║     • System structure                                            ║
║     • Technology choices                                          ║
║     • Design patterns                                             ║
║     • Integration approaches                                      ║
║                                                                   ║
║  Please provide:                                                  ║
║  1. Decision title (what architectural decision)                  ║
║  2. Context (why is this decision needed)                         ║
║  3. The decision and alternatives considered                      ║
║                                                                   ║
╚══════════════════════════════════════════════════════════════════╝

3. Determine Sequence Number

# Count existing ADRs for today
ls .devtrail/02-design/decisions/ADR-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l

4. Check Language and Load Template

Read

.devtrail/config.yml

for language setting:

• en

  (default):

  .devtrail/templates/TEMPLATE-ADR.md

• es

  :

  .devtrail/templates/i18n/es/TEMPLATE-ADR.md

5. Create Document

Fill template with:

• id

  : ADR-YYYY-MM-DD-NNN

• title

  : Architectural decision title

• status

  : draft (always for AI-created ADRs)

• created

  : Current date

• updated

  : Current date

• agent

  : gemini-cli-v1.0

• confidence

  : based on research done

• review_required

  : true (always for ADRs)

• risk_level

  : minimum

  medium

  for architectural decisions

Key sections to fill:

• Status: Note that this was created by AI agent
• Context: Technical and business context, forces at play
• Decision: The architectural decision with justification
• Alternatives Considered: Other options with pros/cons/why not
• Consequences: Positive, negative, neutral
• Affected Components: Table of impacted parts
• Implementation Plan: High-level steps
• Success Metrics: How to validate the decision

Save to:

.devtrail/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md

6. Report Result

⚠️  ADR created (requires human review):
   .devtrail/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md

   Status: draft
   Review Required: YES

DevTrail: Created ADR-YYYY-MM-DD-NNN-description.md (review required)

Examples of Architectural Decisions

• Use PostgreSQL over MongoDB for persistence
• Adopt microservices vs. monolith architecture
• Choose REST vs. GraphQL for API
• Select authentication strategy (JWT, OAuth, etc.)
• Define module boundaries and dependencies
• Establish caching strategy