| 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
Project Integration
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
Templates
This skill includes comprehensive ADR and migration templates:
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:
find docs/adr -name "*.md" -type f -exec grep -l "keyword" {} \;
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:
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:
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 starteddocs/adr/in_progress/ - Implementation currently underwaydocs/adr/implemented/ - Fully implemented and verified
Default: Use not_started/ for new decisions unless implementation begins immediately.
-
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
-
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:
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
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
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
./scripts/find_next_adr_number.sh
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
Skill Type: Project Skill (team workflow)
Audience: @researcher, @planner, any agent making architectural decisions
Last Updated: 2025-10-17
