create-adr-spike

What this skill does

# 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

## 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
- [reference.md](references/reference.md) - Technical documentation, ADR template deep-dive, and comprehensive examples
- [Scripts](scripts/) - Utility scripts for ADR number finding and validation
- [Templates](templates/) - ADR and migration templates for structured decision records

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

4. **Complete Required Sections:**
   - **Status:** Proposed | Accepted | In Progress | Completed
   - **Date:** Current date (YYYY-MM-DD)
   - **Conte