ADR Creator - Structured ADR Creation Process

Purpose

Create Architecture Decision Records in MADR format through a 4-stage process: validation, collection, generation, and confirmation to ensure documentation quality.

Execution Flow

Phase 1: Pre-Creation Check

Purpose: Prevent duplicates and inconsistencies in advance

Actions:

Check for duplicate existing ADRs
Validate naming conventions
Confirm date/version consistency
Verify directory structure

Script: scripts/pre-check.sh

Check Items:

# 1. Duplicate ADR Check
- Title similarity check (warning if Levenshtein distance < 3)
- Search for existing ADRs on same technology/pattern
- Confirm related superseded ADRs

# 2. Naming Convention Validation
- Title length: 5-64 characters
- Prohibited character check (/:*?"<>|)
- Slug generation possibility confirmation

# 3. Date/Version Consistency
- Created date ≤ current date
- Consistency with project version
- Timezone confirmation

# 4. Directory Structure
- Confirm docs/adr/ exists
- Check write permissions
- Verify numbering rules (0001-9999)

Output Example:

🔍 ADR Pre-Creation Check

✅ Duplicate check: No similar ADRs found
✅ Naming convention: OK
✅ Date consistency: OK
⚠️  Warning: ADR-0015 may be related ("Adopt React for UI")
   → Please confirm relevance

✅ Ready to create
Next number: 0023

Phase 2: Template Selection and Section Structure

Purpose: Select appropriate structure based on ADR type

Template Types:

Template	Use Case	Section Characteristics
technology-selection	Technology/library selection	Alternatives comparison focused
architecture-pattern	Architecture pattern	Detailed context & consequences analysis
process-change	Development process changes	Detailed decision drivers
deprecation	Deprecating existing technology	Migration plan required

Selection Process:

📋 ADR Template Selection

Which category does this decision fall into?

1. Technology selection (library, framework, language)
2. Architecture pattern (structure, design policy)
3. Process change (workflow, rules)
4. Deprecation (retiring existing technology)

Selection > 1

✅ Template: technology-selection.md
Required sections:
- Context and Problem Statement
- Considered Options (minimum 3 recommended)
- Pros and Cons of the Options
- Decision Outcome
- Confirmation (implementation verification method)

Phase 3: Reference Collection

Purpose: Systematically collect information that supports the decision

Script: scripts/collect-references.sh

Collection Targets:

# 1. Project Documentation
- Related sections in README.md
- Specifications under docs/
- Related entries in CHANGELOG.md

# 2. Issue Tracker
- GitHub Issues (labels: architecture, decision)
- Related discussion threads
- History leading to the decision

# 3. Pull Requests
- Related implementation PRs
- Review comments
- Performance measurement results

# 4. External Resources
- Official documentation
- Benchmark results
- Community evaluations

Output Format:

## References (auto-collected)

### Within Project
- [README.md#Tech Stack](../README.md#tech-stack)
- [Spec: State Management Requirements](../docs/requirements/state-management.md)

### Issues & PRs
- [Issue #145: State Management Library Selection](https://github.com/org/repo/issues/145)
- [PR #167: Zustand POC Implementation](https://github.com/org/repo/pull/167)

### External Resources
- [Zustand Official Documentation](https://github.com/pmndrs/zustand)
- [State of JS 2024: State Management](https://stateofjs.com/...)
- [Benchmark Results](https://npmtrends.com/zustand-vs-redux)

Implementation:

#!/bin/bash
# scripts/collect-references.sh

KEYWORD="$1"  # e.g., "zustand" "state management"

# GitHub Issues search (using gh CLI)
echo "### Issues & PRs"
gh issue list --search "$KEYWORD" --state all --limit 5 \
  --json number,title,url \
  --jq '.[] | "- [Issue #\(.number): \(.title)](\(.url))"'

# Project-wide grep
echo "### Within Project"
rg -l "$KEYWORD" docs/ README.md 2>/dev/null | while read file; do
  echo "- [$file]($file)"
done

Phase 4: Proofreading & Verification Checklist

Purpose: Quality assurance after ADR completion

Script: scripts/validate-adr.sh

Verification Items:

4-1. Impact Analysis

# references/impact-analysis.md

## Impact Analysis Checklist

### Codebase
- [ ] Identify number of affected files (estimate: ___ files)
- [ ] List of modules requiring changes
- [ ] Presence of breaking changes
- [ ] Need for compatibility layer

### Dependencies
- [ ] Need to update package.json
- [ ] Confirm conflicts with dependent libraries
- [ ] Confirm version constraints

### Team
- [ ] Number of affected team members
- [ ] Learning cost estimate (___ hours/person)
- [ ] Documentation update tasks

4-2. Test Coverage

# references/test-coverage.md

## Test Update Checklist

- [ ] Identify scope of existing test updates
- [ ] New tests needed (estimate: ___ tests)
- [ ] Impact on E2E tests
- [ ] Need for performance tests
- [ ] Regression test plan

4-3. Rollback Plan

# references/rollback-plan.md

## Rollback Plan Checklist

### Preparation
- [ ] Create rollback procedure document
- [ ] Identify backup targets
- [ ] Define rollback triggers

### Verification
- [ ] Estimate rollback time (___ minutes)
- [ ] Data integrity assurance method
- [ ] Possibility of partial/gradual rollback

Validation Script Execution Example:

# scripts/validate-adr.sh 0023-adopt-zustand.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ADR Validation Report: 0023-adopt-zustand.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Required sections: Complete
✅ MADR format: Compliant
⚠️  Warning: Confirmation section is empty
⚠️  Warning: Only 2 references (recommended: 3+)

📊 Checklist Progress:
  Impact analysis: 3/5 complete
  Test updates: 0/5 not started  ← Action needed
  Rollback plan: 2/3 complete

Recommendation: Complete the test update checklist

Phase 5: Index Update & Link Generation

Purpose: Visualize relationships between ADRs and improve discoverability

Script: scripts/update-index.sh

Actions:

5-1. Auto-Generate ADR List

# docs/adr/README.md auto-update

## Architecture Decision Records

| Number | Title | Status | Date |
|--------|-------|--------|------|
| [0023](0023-adopt-zustand.md) | Adopt Zustand for State Management | proposed | 2025-10-21 |
| [0022](0022-migration-turborepo.md) | Migrate to Turborepo | accepted | 2025-10-15 |
| [0021](0021-typescript-strict.md) | Enable TypeScript Strict Mode | accepted | 2025-10-10 |

### By Status
- **Proposed**: 0023
- **Accepted**: 0015, 0016, 0021, 0022
- **Deprecated**: 0008
- **Superseded**: 0003 → 0021

5-2. Cross-Link Related ADRs

# Auto-added within ADR-0023

## Related ADRs

### Depends On
- [ADR-0015: Adopt React for UI](0015-adopt-react-for-ui.md) - Prerequisite for state management

### Related
- [ADR-0021: TypeScript Strict Mode](0021-typescript-strict.md) - Type safety enhancement

### May Supersede
- [ADR-0008: Use Redux for State](0008-use-redux-for-state.md) - Future replacement candidate

Link Generation Algorithm:

# Keyword-based relevance detection
KEYWORDS=$(extract_keywords "$ADR_FILE")  # "zustand", "state", "react"

# Calculate relevance score from existing ADRs
for existing_adr in docs/adr/*.md; do
  score=$(calculate_relevance "$KEYWORDS" "$existing_adr")
  if [ $score -gt 3 ]; then
    echo "Related: $existing_adr (score: $score)"
  fi
done

Phase 6: Retry Procedures on Failure

Purpose: Automatic recovery on errors and clear guidance

Error Patterns and Handling:

6-1. Path Resolution Error

❌ Error: Cannot create docs/adr/0023-adopt-zustand.md
   Reason: Relative path resolution failed

🔧 Auto-fix attempt:
1. Convert relative path → absolute path
   Before: docs/adr/
   After:  /Users/user/project/docs/adr/

2. Attempt directory creation
   mkdir -p /Users/user/project/docs/adr/

3. Retrying...

6-2. Template Selection Failure

❌ Error: Selected template not found
   Template: technology-selection.md
   Path: .claude/skills/creating-adrs/assets/

🔧 Fallback:
1. Use default template
2. Suggest custom template
   - Extract structure from similar ADR
   - Start with MADR minimal structure

Selection > 1 (default)

✅ Continuing with default template

6-3. Reference Collection Failure

⚠️  Warning: GitHub Issues collection failed
   Reason: gh CLI not authenticated

🔧 Alternatives:
1. Search local files only (can continue)
2. Enter references manually
3. Add later (edit after ADR creation)

Selection > 1

✅ Continuing with local references only
   Within project: 3 items found
   External links: Manual input required

Usage

Basic Invocation

# /adr command automatically uses this skill
/adr "Adopt Zustand for State Management"

Skill Operation Flow

1. Pre-Check execution (automatic)
   ↓
2. Template selection (interactive)
   ↓
3. Reference collection (automatic + manual supplement)
   ↓
4. Information input (interactive)
   ↓
5. ADR generation
   ↓
6. Validation execution (automatic)
   ↓
7. Checklist presentation (confirmation)
   ↓
8. Index update (automatic)
   ↓
9. Complete

Configuration Options

SKILL.md Frontmatter Extension

---
# Existing settings
name: creating-adrs
description: Create high-quality Architecture Decision Records through a structured process

# Additional settings
config:
  strict_mode: true              # All checklists required
  auto_collect_references: true  # Automatic reference collection
  template_fallback: minimal     # Behavior on template failure
  index_auto_update: true        # Automatic index update
  duplicate_threshold: 0.7       # Similarity threshold for duplicate detection (0-1)
---

Phased Implementation Plan

Phase 1 (Immediately Implementable)

✅ pre-check.sh: Duplicate/naming convention check
✅ Template selection UI
✅ Basic index update

Phase 2 (Within 1 Week)

⏳ collect-references.sh: GitHub integration
⏳ validate-adr.sh: Completeness verification
⏳ Checklist templates

Phase 3 (Within 2 Weeks)

⏳ Related ADR auto-linking
⏳ Enhanced error handling
⏳ Statistics dashboard

Troubleshooting

Q: Scripts not executing

# Grant execution permissions
chmod +x .claude/skills/creating-adrs/scripts/*.sh

Q: GitHub integration not working

# Check gh CLI authentication
gh auth status

# If not authenticated
gh auth login

Q: Want to customize templates

# Place project-specific templates
.claude/skills/creating-adrs/assets/custom-template.md

# Will appear in selection options during ADR creation

Integration Checklist

For verifying skills integration status:

Expected Improvements

Item	Before	After	Improvement
ADR creation time	15 min	8 min	47% reduction
Duplicate ADR rate	5%	0%	100% eliminated
Missing required sections	20%	0%	100% eliminated
Average reference count	1.5	3.2	113% increase
README.md update forgotten	30%	0%	100% eliminated

creating-adrs