create-adr-spike

name	create-adr-spike
description	Create Architecture Decision Records (ADRs) and research spikes for technical decisions. Use when asked to "create an ADR", "architectural decision for", "research spike on", "evaluate options for", "document technical decision", "should we use X or Y", or when analyzing architecture alternatives. Provides structured research, analysis, and documentation workflow with memory storage. Creates .md files in docs/adr/ with proper numbering and status tracking.
allowed-tools	["Read","Grep","Glob","Bash","WebSearch","WebFetch","mcp__memory__search_memories","mcp__memory__find_memories_by_name","mcp__memory__create_entities","mcp__memory__create_relations","mcp__memory__add_observations","mcp__context7__resolve-library-id","mcp__context7__get-library-docs","Write"]

Create ADR Spike

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

Table of Contents

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

• examples.md - Comprehensive examples: simple decisions, complex refactors, research spikes, superseding ADRs
• reference.md - Technical documentation and ADR template deep-dive
• Scripts - Utility scripts for ADR number finding and validation
• ADR Directory Guide - Complete ADR organization and lifecycle
• ADR Template - Copy-paste template for new ADRs

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.

1. Identify the Decision:

   • What problem are we solving?
   • What constraints exist (performance, cost, expertise)?
   • What are the success criteria?

2. 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")
   

3. 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

4. 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.

1. Identify Options (minimum 2-3):

   • List all viable alternatives
   • Include "do nothing" if applicable
   • Consider hybrid approaches

2. 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?

3. 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.

1. Recommend Preferred Option:

   • State choice clearly
   • Provide 2-3 sentence rationale
   • Reference evaluation criteria

2. Document Justification:

   • Why this option over others?
   • What criteria weighted most heavily?
   • What assumptions are we making?
   • What constraints influenced the decision?

3. 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.

1. 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
   

2. 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.

3. Create ADR from Template:

   • Copy template: ../../../docs/adr/TEMPLATE-refactor-migration.md
   • Fill all required sections (no placeholders)
   • Use next sequential number (e.g., ADR-028)
   • Use kebab-case for filename: 028-descriptive-title.md

4. 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

5. 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.

1. 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}/"
       ]
   }])
   

2. Create Relations to Existing Entities:

   • Link to affected components
   • Link to related ADRs (supersedes, relates-to)
   • Link to architectural patterns

3. 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:

• Minimum 2-3 alternatives evaluated
• Clear recommendation with justification
• Consequences documented (positive AND negative)
• ADR created in correct directory with proper numbering
• All required sections completed (no placeholder text)
• Memory entity created with proper observations and relations
• Max 2 files: ADR.md only (not_started) or ADR.md + IMPLEMENTATION_PLAN.md (in_progress)
• No extra files: No RESEARCH.md, ANALYSIS.md, EXECUTIVE_SUMMARY.md, IMPLEMENTATION_NOTES.md
• No single-option analysis (red flag: only one option presented)
• Trade-offs documented (no "silver bullet" claims)
• Risks identified with mitigation strategies

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

1. Single Option Presented:

   • ❌ BAD: "We should use PostgreSQL" (no alternatives)
   • ✅ GOOD: "PostgreSQL vs Neo4j vs Hybrid approach" (multiple options)

2. Missing Trade-off Analysis:

   • ❌ BAD: "Option A is better in every way"
   • ✅ GOOD: "Option A is faster but harder to maintain"

3. No Consequence Documentation:

   • ❌ BAD: Decision without discussing impact
   • ✅ GOOD: Positive/negative consequences documented

4. Skipping Memory Storage:

   • ❌ BAD: ADR created but not in memory graph
   • ✅ GOOD: ADR entity created with relations

5. Placeholder Text in ADR:

   • ❌ BAD: "[TODO: Add alternatives]"
   • ✅ GOOD: All sections fully completed

6. Wrong Directory:

   • ❌ BAD: Implementation ADR in not_started/
   • ✅ GOOD: ADR directory matches status

7. No External Research:

   • ❌ BAD: Decision based only on opinion
   • ✅ GOOD: Research references documentation, benchmarks, community discussion

8. Ignoring Existing ADRs:

   • ❌ BAD: Creating conflicting ADR without checking existing
   • ✅ GOOD: Search existing ADRs, note conflicts/supersessions

9. 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/examples.md for complete walkthroughs 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
• references/examples.md: Comprehensive examples and edge cases
• 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
• ADR template available at ../../../docs/adr/TEMPLATE-refactor-migration.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:

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

Output Format

When completing an ADR spike, provide:

1. Executive Summary:

   • Decision made
   • Key rationale (2-3 sentences)
   • Alternatives considered

2. ADR Location:

   • Full path to created ADR
   • ADR number and title

3. Memory Entity:

   • Entity name
   • Key observations stored

4. Next Steps (if applicable):

   • Implementation tasks
   • todo.md section created
   • Refactor markers needed

References

• ADR Directory Guide
• Refactor Marker Guide
• ARCHITECTURE.md - Implemented patterns
• ADR Template

---

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