Create ADR Spike

Standardized workflow for creating Architecture Decision Records (ADRs) and conducting research spikes for technical decisions.

When to Use This Skill

Explicit Triggers:

"Create an ADR for [decision]"
"Architecture decision for [problem]"
"Research spike on [topic]"
"Evaluate options for [choice]"
"Document technical decision about [subject]"
"Should we use X or Y?"

Implicit Triggers:

Comparing multiple technical alternatives
Making architectural choices that affect system design
Evaluating libraries, frameworks, or patterns
Deciding on refactoring approaches
Documenting important technical trade-offs

Debugging/Analysis Triggers:

"What decisions led to this architecture?"
"Why did we choose [technology/pattern]?"
"Search existing ADRs for [topic]"

When NOT to Use:

Simple code refactoring (no architectural impact)
Bug fixes without design implications
Minor configuration changes
Routine maintenance tasks

Core Sections

Quick Start - What this skill does and when to use it
Workflow - Complete 5-phase ADR creation process
- Phase 1: Research (Discovery) - Gather context and search existing knowledge
- Phase 2: Analysis (Evaluation) - Evaluate alternatives systematically
- Phase 3: Decision (Recommendation) - Make clear, justified recommendation
- Phase 4: Documentation (Formalization) - Create permanent ADR record
- Phase 5: Memory Storage (Persistence) - Store decision in memory graph
Quality Checklist - Verification before marking spike complete
Anti-Patterns to Avoid - Common mistakes and correct approaches

Project Integration

Project-Specific Conventions - ADR directory structure and naming
Examples - Complete walkthroughs and use cases
Output Format - How to present completed ADR spike results
Success Criteria - When an ADR spike is complete

Supporting Resources

reference.md - Technical documentation, ADR template deep-dive, and comprehensive examples
Scripts - Utility scripts for ADR number finding and validation
Templates - ADR and migration templates for structured decision records

Additional Information

Requirements - Skills, tools, project setup, and knowledge needed
Troubleshooting - Common issues and solutions
References - Related documentation and guides

Templates

This skill includes comprehensive ADR and migration templates:

templates/adr-template.md - Complete ADR structure with:
- Status and metadata frontmatter
- Context, decision, and consequences sections
- Implementation strategy and validation plan
- Migration path with before/after examples
- Alternatives considered and trade-off analysis
- Related decisions and references
templates/migration-template.md - Detailed migration/refactor plan with:
- Current state and desired state analysis
- Phased migration path with detailed steps
- Risk analysis and mitigation strategies
- Comprehensive rollback procedures
- Testing strategy and monitoring plan
- Communication and training plans

Usage: Reference these templates when creating ADRs from spikes or planning complex migrations/refactors.

Quick Start

Invoke this skill when you need to:

Document an architectural decision
Research technical alternatives
Evaluate competing solutions
Create a formal decision record

Example invocation:

"Create an ADR for choosing between PostgreSQL and Neo4j for our graph storage"

Workflow

Phase 1: Research (Discovery)

Objective: Gather all relevant context before making a recommendation.

Identify the Decision:
- What problem are we solving?
- What constraints exist (performance, cost, expertise)?
- What are the success criteria?

Search Existing Knowledge:

# Search existing ADRs for related decisions
find docs/adr -name "*.md" -type f -exec grep -l "keyword" {} \;

# Search project memory for patterns
mcp__memory__search_memories(query="related topic")

Research External Resources (if needed):
- Use mcp__context7__resolve-library-id to find library documentation
- Use mcp__context7__get-library-docs to get detailed technical info
- Use WebSearch for recent discussions, benchmarks, or comparisons
- Use WebFetch to extract specific documentation pages
Document Findings:
- Create ADR directory and start drafting ADR.md:
```
docs/adr/not_started/{number}-{kebab-case-title}/
└── ADR.md   # Draft: add research findings to "Context" and "Research" sections
```
- DO NOT create separate RESEARCH.md, ANALYSIS.md, or EXECUTIVE_SUMMARY.md files
- DO NOT put research in .claude/artifacts/
- All research goes directly into ADR.md sections

Phase 2: Analysis (Evaluation)

Objective: Evaluate alternatives systematically.

Identify Options (minimum 2-3):
- List all viable alternatives
- Include "do nothing" if applicable
- Consider hybrid approaches
Evaluate Each Option: For each alternative, document:
- Pros: Benefits and strengths
- Cons: Drawbacks and weaknesses
- Performance: Speed, scalability, resource usage
- Maintainability: Code complexity, debugging, testability
- Cost: Development time, operational cost, learning curve
- Team Fit: Expertise required, training needed
- Risks: What could go wrong?
- Trade-offs: What are we giving up?
Create Comparison Matrix:

Criteria Option A Option B Option C
Performance High Medium Low
Maintainability Medium High Low
Cost Low High Medium
Team Fit High Medium Low

Criteria	Option A	Option B	Option C
Performance	High	Medium	Low
Maintainability	Medium	High	Low
Cost	Low	High	Medium
Team Fit	High	Medium	Low

Phase 3: Decision (Recommendation)

Objective: Make a clear, justified recommendation.

Recommend Preferred Option:
- State choice clearly
- Provide 2-3 sentence rationale
- Reference evaluation criteria
Document Justification:
- Why this option over others?
- What criteria weighted most heavily?
- What assumptions are we making?
- What constraints influenced the decision?
Identify Consequences:
- Positive: What improves?
- Negative: What gets harder?
- Risks: What could fail?
- Mitigations: How to reduce risks?

Phase 4: Documentation (Formalization)

Objective: Create permanent ADR record.

Determine ADR Number:

# Find highest existing ADR number across all status directories
find docs/adr -name "[0-9]*.md" | \
  sed 's/.*\/\([0-9]*\)-.*/\1/' | \
  sort -n | tail -1

Choose ADR Directory:
- docs/adr/not_started/ - Decision made, implementation not started
- docs/adr/in_progress/ - Implementation currently underway
- docs/adr/implemented/ - Fully implemented and verified
Default: Use not_started/ for new decisions unless implementation begins immediately.
Create ADR from Template:
- Copy template: templates/adr-template.md or templates/migration-template.md
- Fill all required sections (no placeholders)
- Use next sequential number (e.g., ADR-028)
- Use kebab-case for filename: 028-descriptive-title.md
Complete Required Sections:
- Status: Proposed | Accepted | In Progress | Completed
- Date: Current date (YYYY-MM-DD)
- Context: Problem statement, current state, motivation
- Decision: Chosen approach, scope, pattern
- Consequences: Positive, negative, migration strategy
- Alternatives Considered: At least 2-3 options with pros/cons
- References: Links to research, docs, discussions
Add Implementation Tracking (if applicable):
- Files affected
- Completion criteria
- Testing strategy
- Code marker guidelines

Phase 5: Memory Storage (Persistence)

Objective: Store decision in memory graph for future retrieval.

Create Memory Entity:

mcp__memory__create_entities(entities=[{
    "name": f"ADR-{number}: {title}",
    "type": "ArchitectureDecision",
    "observations": [
        f"Status: {status}",
        f"Decision: {chosen_option}",
        f"Rationale: {key_reason}",
        f"Date: {date}",
        f"Location: docs/adr/{status_dir}/{number}-{kebab-case-title}/"
    ]
}])

Create Relations to Existing Entities:
- Link to affected components
- Link to related ADRs (supersedes, relates-to)
- Link to architectural patterns
Verify Document Structure:
- Maximum 2 files per ADR - see "Document Structure Rule" section
- For not_started/: Only ADR.md
- For in_progress/: ADR.md + IMPLEMENTATION_PLAN.md
- NO separate RESEARCH.md, ANALYSIS.md, EXECUTIVE_SUMMARY.md, or IMPLEMENTATION_NOTES.md
- NO documents in .claude/artifacts/

Quality Checklist

Before marking the spike complete, verify:

Document Structure Rule (CRITICAL)

Minimal documents. No redundancy. Human-readable.

Document Count by Status

Status	Documents	Contents
`not_started/`	1 file: ADR.md	Research + Analysis + Decision
`in_progress/`	2 files: ADR.md + IMPLEMENTATION_PLAN.md	Add implementation details
`implemented/`	1-2 files	Same as in_progress (plan becomes historical record)

✅ CORRECT Structure

For not_started/ (decision made, not yet implementing):

docs/adr/not_started/005-subprocess-daemon-architecture/
└── ADR.md    # Contains: Executive Summary, Research, Analysis, Decision, Alternatives

For in_progress/ (actively implementing):

docs/adr/in_progress/005-subprocess-daemon-architecture/
├── ADR.md                  # The decision (research + analysis + decision)
└── IMPLEMENTATION_PLAN.md  # How to build it (phases + tasks + notes)

❌ WRONG Structure (Too Many Documents)

docs/adr/in_progress/005-.../
├── ADR.md
├── RESEARCH.md              # ❌ WRONG: Put in ADR.md
├── ANALYSIS.md              # ❌ WRONG: Put in ADR.md
├── EXECUTIVE_SUMMARY.md     # ❌ WRONG: Put in ADR.md
├── IMPLEMENTATION_PLAN.md
└── IMPLEMENTATION_NOTES.md  # ❌ WRONG: Put in IMPLEMENTATION_PLAN.md

The Rule

ADR.md = Research + Analysis + Executive Summary + Decision + Alternatives
IMPLEMENTATION_PLAN.md = Phases + Tasks + Developer Notes (only when in_progress/)
That's it. 1-2 files maximum.

Anti-Patterns to Avoid

Single Option Presented:
- ❌ BAD: "We should use PostgreSQL" (no alternatives)
- ✅ GOOD: "PostgreSQL vs Neo4j vs Hybrid approach" (multiple options)
Missing Trade-off Analysis:
- ❌ BAD: "Option A is better in every way"
- ✅ GOOD: "Option A is faster but harder to maintain"
No Consequence Documentation:
- ❌ BAD: Decision without discussing impact
- ✅ GOOD: Positive/negative consequences documented
Skipping Memory Storage:
- ❌ BAD: ADR created but not in memory graph
- ✅ GOOD: ADR entity created with relations
Placeholder Text in ADR:
- ❌ BAD: "[TODO: Add alternatives]"
- ✅ GOOD: All sections fully completed
Wrong Directory:
- ❌ BAD: Implementation ADR in not_started/
- ✅ GOOD: ADR directory matches status
No External Research:
- ❌ BAD: Decision based only on opinion
- ✅ GOOD: Research references documentation, benchmarks, community discussion
Ignoring Existing ADRs:
- ❌ BAD: Creating conflicting ADR without checking existing
- ✅ GOOD: Search existing ADRs, note conflicts/supersessions
Splitting Documents Across Locations:
- ❌ BAD: ADR in docs/adr/, research in .claude/artifacts/
- ✅ GOOD: ALL documents in docs/adr/{status_dir}/{number}-{kebab-case-title}/

Project-Specific Conventions

ADR Directory Structure (This Project)

docs/adr/
├── implemented/    # Completed ADRs (11+ ADRs)
├── in_progress/    # Active implementation (4+ ADRs)
├── not_started/    # Proposed/accepted, not started (10+ ADRs)
├── TEMPLATE-refactor-migration.md
└── README.md

Numbering Convention

Use 3-digit format: 001, 028, 127
Find highest number across ALL status directories
Use next sequential number
Do not reuse numbers

Filename Convention

Format: {number}-{kebab-case-title}.md
Example: 028-indexing-orchestrator-extraction.md
Keep titles concise (3-7 words)

Status Values

Proposed: Initial draft, seeking approval
Accepted: Approved, awaiting implementation
In Progress: Currently implementing
Completed: Fully implemented and verified
Superseded: Replaced by newer ADR

Refactor Markers (for in-progress ADRs)

If ADR is in in_progress/, add file-level markers in affected code:

# =============================================================================
# TODO: "Section Name"
# REFACTOR: [ADR-XXX] Brief description
# WHY: One-line reason
# STARTED: YYYY-MM-DD
# STATUS: IN_PROGRESS
# PERMANENT_RECORD: docs/adr/in_progress/XXX-title.md
# ACTIVE_TRACKING: todo.md "Section Name"
# =============================================================================

See: Refactor Marker Guide

Integration with todo.md

For ADRs requiring implementation:

Create section in ./todo.md tracking tasks
Reference in ADR's "Active Tracking" section
Update ADR's "Progress Log" as work proceeds

Examples

Python Examples

validate_adr.py - Validate ADR completeness and format
find_next_adr_number.sh - Find next ADR number in sequence

Complete Walkthroughs

See references/reference.md for detailed examples of:

Simple architectural decision (library choice)
Complex refactor/migration ADR
Research spike with external investigation
Superseding an existing ADR

Supporting Files

references/reference.md: Detailed technical documentation, ADR template deep-dive, and comprehensive examples
templates/adr-template.md: Complete ADR structure with all required sections
templates/migration-template.md: Detailed migration/refactor planning template
scripts/validate_adr.py: Validation script for ADR completeness
scripts/find_next_adr_number.sh: Utility to find next ADR number

Requirements

Skills & Tools:

Skill tool access: Read, Grep, Glob, Bash, Write
MCP tools: mcp__memory__, mcp__context7__ (for research)
Web tools: WebSearch, WebFetch (for external research)

Project Setup:

docs/adr/ directory structure exists with status subdirectories (in projects using this skill)
ADR templates available at templates/adr-template.md and templates/migration-template.md
Memory system configured for entity storage

Knowledge:

Understanding of Clean Architecture principles (for this project)
Ability to evaluate technical trade-offs
Familiarity with ADR format and structure

Troubleshooting

Issue: Can't find next ADR number

# Solution: Use helper script
./scripts/find_next_adr_number.sh

# Or manually:
find docs/adr -name "[0-9]*.md" | sed 's/.*\/\([0-9]*\)-.*/\1/' | sort -n | tail -1

Issue: Don't know which directory to use

not_started/: Decision made, no implementation yet (default)
in_progress/: Currently implementing
implemented/: Fully complete and verified

Issue: Alternatives seem equivalent

Good! Document that in the ADR
Explain why you chose one over the other (team fit, learning curve, etc.)
Consider hybrid approaches

Issue: Only one viable option

❌ RED FLAG - dig deeper
Minimum 2-3 alternatives required
Include "do nothing" as an option if applicable
Consider different implementation approaches of the same technology

Issue: Research taking too long

Set time box (1-2 hours for simple decisions, 4-8 hours for complex)
Focus on key decision criteria
Note what you didn't research in ADR limitations section
Can always update ADR later with more research

Issue: Memory entity creation fails

Verify memory system is configured and running
Check entity name doesn't already exist
Simplify observations if too complex
Skip memory storage if blocked, but note in ADR

Success Criteria

An ADR spike is complete when:

✅ Research conducted (existing ADRs, memory, external sources)
✅ Alternatives evaluated (2-3+ options)
✅ Recommendation made with justification
✅ ADR created with all required sections
✅ ADR placed in correct directory with proper numbering
✅ Memory entity created with relations
✅ Research artifacts saved and referenced
✅ Quality checklist verified

Output Format

When completing an ADR spike, provide:

Executive Summary:
- Decision made
- Key rationale (2-3 sentences)
- Alternatives considered
ADR Location:
- Full path to created ADR
- ADR number and title
Memory Entity:
- Entity name
- Key observations stored
Next Steps (if applicable):
- Implementation tasks
- todo.md section created
- Refactor markers needed

References

Refactor Marker Guide
ADR Template
Migration Template
Reference Documentation - Detailed examples and walkthroughs

Skill Type: Project Skill (team workflow) Audience: @researcher, @planner, any agent making architectural decisions Last Updated: 2025-10-17