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](#quick-start) - What this skill does and when to use it
- [Workflow](#workflow) - Complete 5-phase ADR creation process
  - [Phase 1: Research (Discovery)](#phase-1-research-discovery) - Gather context and search existing knowledge
  - [Phase 2: Analysis (Evaluation)](#phase-2-analysis-evaluation) - Evaluate alternatives systematically
  - [Phase 3: Decision (Recommendation)](#phase-3-decision-recommendation) - Make clear, justified recommendation
  - [Phase 4: Documentation (Formalization)](#phase-4-documentation-formalization) - Create permanent ADR record
  - [Phase 5: Memory Storage (Persistence)](#phase-5-memory-storage-persistence) - Store decision in memory graph
- [Quality Checklist](#quality-checklist) - Verification before marking spike complete
- [Anti-Patterns to Avoid](#anti-patterns-to-avoid) - Common mistakes and correct approaches

### Project Integration
- [Project-Specific Conventions](#project-specific-conventions) - ADR directory structure and naming
- [Examples](#examples) - Complete walkthroughs and use cases
- [Output Format](#output-format) - How to present completed ADR spike results
- [Success Criteria](#success-criteria) - When an ADR spike is complete

### Supporting Resources
- [examples.md](references/examples.md) - Comprehensive examples: simple decisions, complex refactors, research spikes, superseding ADRs
- [reference.md](references/reference.md) - Technical documentation and ADR template deep-dive
- [Scripts](scripts/) - Utility scripts for ADR number finding and validation
- [ADR Directory Guide](../../../docs/ADR-DIRECTORY-GUIDE.md) - Complete ADR organization and lifecycle
- [ADR Template](../../../docs/adr/TEMPLATE-refactor-migration.md) - Copy-paste template for new ADRs

### Additional Information
- [Requirements](#requirements) - Skills, tools, project setup, and knowledge needed
- [Troubleshooting](#troubleshooting) - Common issues and solutions
- [References](#references) - Related documentation and guides

## Templates

This skill includes comprehensive ADR and migration templates:

- **[templates/adr-template.md](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](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:**
   ```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")
   ```

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:**
   ```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
   ```

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:**
   ```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}/"
       ]
   }])
   ```

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:
```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](../detect-refactor-markers/references/refactor-marker-guide.md)

### 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](./scripts/validate_adr.py) - Validate ADR completeness and format
- [find_next_adr_number.sh](./scripts/find_next_adr_number.sh) - Find next ADR number in sequence

### Complete Walkthroughs

See [references/examples.md](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](references/reference.md):** Detailed technical documentation, ADR template deep-dive
- **[references/examples.md](references/examples.md):** Comprehensive examples and edge cases
- **[scripts/validate_adr.py](scripts/validate_adr.py):** Validation script for ADR completeness
- **[scripts/find_next_adr_number.sh](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**
```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:
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](../../../docs/ADR-DIRECTORY-GUIDE.md)
- [Refactor Marker Guide](../detect-refactor-markers/references/refactor-marker-guide.md)
- [ARCHITECTURE.md](../../../ARCHITECTURE.md) - Implemented patterns
- [ADR Template](../../../docs/adr/TEMPLATE-refactor-migration.md)

---

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