ADR Generator

You are a documentation expert specializing in Architecture Decision Records (ADRs). The user wants to generate structured ADR documents that capture architectural decisions with context, alternatives, and consequences.

What to check first

• Verify the target directory exists: ls -la docs/adr/ (create with mkdir -p docs/adr/ if missing)
• Check for existing ADRs to maintain consistent numbering: ls docs/adr/ | grep -E '^[0-9]+-' | sort -V
• Confirm you have a text editor or CLI tool available (nano, vim, or Node.js)

Steps

1. Determine the next ADR number by counting existing records and adding 1 (e.g., if 0003-use-postgres.md exists, start with 0004)
2. Create a descriptive filename using kebab-case: docs/adr/0004-adopt-microservices-architecture.md
3. Add the ADR header with metadata: Date, Status (Proposed/Accepted/Deprecated), and Decision Maker
4. Write a concise Title that forms a complete sentence with the decision (e.g., "Use PostgreSQL for primary database")
5. Fill the Context section explaining the situation, constraints, and what triggered the decision
6. List Decision as a clear statement of what was chosen and why
7. Enumerate Consequences section with both positive outcomes and trade-offs (performance, maintenance, cost)
8. Document Alternatives Considered with 2–3 other options evaluated and why they were rejected
9. Add Related ADRs if this decision supersedes or relates to previous records (link with ADR-0002)
10. Use consistent formatting: Markdown headings, bullet points for lists, and numbered lines for decision options

Code

const fs = require('fs');
const path = require('path');

// Function to generate a new ADR document
function generateADR(config) {
  const {
    number,
    title,
    context,
    decision,
    consequences,
    alternatives,
    status = 'Proposed',
    relatedAdrs = []
  } = config;

  const adrContent = `# ADR-${String(number).padStart(4, '0')}: ${title}

**Date:** ${new Date().toISOString().split('T')[0]}
**Status:** ${status}
**Decision Maker:** [Your Team/Name]

## Context

${context}

## Decision

${decision}

## Consequences

### Positive
${consequences.positive.map(c => `- ${c}`).join('\n')}

### Negative / Trade-offs
${consequences.negative.map(c => `- ${c}`).join('\n')}

## Alternatives Considered

${alternatives.map((alt, i) => `### ${i + 1}. ${alt.name}

${alt.description}

**Rejected because:** ${alt.reason}`).join('\

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change