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:

code

"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:

bash

# 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:
  code
  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

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:

bash

# 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:

python

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):

code

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

For in_progress/ (actively implementing):

code

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)

code

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)

code

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:

python

# =============================================================================
# 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

bash

# 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

create-adr-spike

Create ADR Spike

When to Use This Skill

Table of Contents

Core Sections

Project Integration

Supporting Resources

Additional Information

Templates

Quick Start

Workflow

Phase 1: Research (Discovery)

Phase 2: Analysis (Evaluation)

Phase 3: Decision (Recommendation)

Phase 4: Documentation (Formalization)

Phase 5: Memory Storage (Persistence)

Quality Checklist

Document Structure Rule (CRITICAL)

Document Count by Status

✅ CORRECT Structure

❌ WRONG Structure (Too Many Documents)

The Rule

Anti-Patterns to Avoid

Project-Specific Conventions

ADR Directory Structure (This Project)

Numbering Convention

Filename Convention

Status Values

Refactor Markers (for in-progress ADRs)

Integration with todo.md

Examples

Python Examples

Complete Walkthroughs

Supporting Files

Requirements

Troubleshooting

Success Criteria

Output Format

References

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