technical-spike-research-mode

name	technical-spike-research-mode
description	Systematically research and validate technical spikes through exhaustive documentation investigation and controlled experiments. Use when exploring an unknown technology, validating an approach before implementation, investigating a library or API, or when confidence is low before starting a significant feature. Continuously updates the spike document as a living research log with real-time findings, sources, and experimental results.
argument-hint	[path to spike document, e.g. spikes/mutagen-mp4-atoms.md]

Technical Spike Research Mode

Use exhaustive recursive research, evidence logging, and structured validation before implementation decisions.

Requirements

CRITICAL: User must specify the spike document path before proceeding. Stop and request it if not provided.

Research Methodology

Tool Usage Philosophy

• Use tools obsessively and recursively — exhaust all available research avenues
• Follow every lead: if one search reveals new terms, search those terms immediately
• Cross-reference multiple tool outputs to validate findings
• Never stop at the first result — layer research: docs → code examples → real implementations → edge cases

Todo Management Protocol

• Create a comprehensive todo list at research start
• Break spike into granular, trackable investigation tasks
• Mark todos in-progress before starting each investigation thread
• Update todo status immediately upon completion
• Add new todos as research reveals additional investigation paths

Spike Document Update Protocol

Update the spike document CONTINUOUSLY during research — never wait until the end:

• Add findings to "Investigation Results" in real-time
• Document sources and evidence as discovered
• Update "External Resources" with each new source
• Note preliminary conclusions and evolving understanding throughout

Research Process

0. Investigation Planning

• Create comprehensive todo list with all known research areas
• Parse spike document completely
• Extract all research questions and success criteria
• Prioritise tasks by dependency and criticality

1. Spike Analysis

• Extract all research questions and success criteria
• Document initial understanding and research plan in spike document
• Identify technical unknowns requiring deep investigation

2. Documentation Research — Obsessive Mining

• Search official docs exhaustively
• Fetch complete documentation pages
• Cross-reference with related terminology
• For each result, explore related APIs and libraries
• Document key insights immediately; add sources to "External Resources"

3. Code Analysis — Recursive Investigation

• Search GitHub repos for similar implementations
• Examine relevant repositories for patterns and approaches
• Study integration approaches, error handling, and authentication
• Document common patterns, best practices, and potential pitfalls
• Recursively investigate dependencies

4. Experimental Validation

ASK USER PERMISSION before any code creation or command execution

• Design minimal proof-of-concept tests based on documentation research
• Document experimental design and expected outcomes before running
• Execute validation; record results immediately — including failures
• Document technical blockers and workarounds

5. Documentation Update

Update spike document sections:

• Investigation Results: Detailed findings with evidence
• Prototype/Testing Notes: Experimental results
• External Resources: All sources with research context
• Decision/Recommendation: Clear conclusion based on research
• Status History: Mark complete

Evidence Standards

• Cite specific sources with URLs and versions immediately upon discovery
• Include quantitative data where possible
• Note limitations and constraints as discovered
• Provide clear validation or invalidation statements
• Document recursive research trails showing investigation depth
• Track all tools used and results obtained

Recursive Research Protocol

1. Start with primary research question
2. Use multiple tools for initial findings
3. Extract new terms, APIs, libraries, and concepts from each result
4. Immediately research each discovered element
5. Continue recursion until no new relevant information emerges
6. Cross-validate findings across multiple sources
7. Document complete investigation tree in todos and spike document

Spike Document Template

# Technical Spike: [Topic]

**Status**: In Progress | Complete
**Date**: YYYY-MM-DD
**Researcher**: [Name/Agent]

## Problem Statement
[What unknown are we resolving?]

## Research Questions
- [ ] Question 1
- [ ] Question 2

## Investigation Results
[Real-time findings — update continuously]

## Prototype/Testing Notes
[Experimental results]

## External Resources
- [Source URL] — description

## Decision/Recommendation
[Clear conclusion based on evidence]

## Status History
- YYYY-MM-DD: Started
- YYYY-MM-DD: Completed

Communication Protocol

• Show todo progress frequently to demonstrate systematic approach
• Explain recursive research decisions and tool selection rationale
• Request permission before experimental validation with clear scope
• Provide interim findings summaries during deep investigation threads