| name | spike |
| description | Time-boxed technical investigation with structured findings document, tech spike, research spike, proof of concept. Use for time-boxed research, technical spikes, or proof of concept work. |
Technical Spike
Structured, time-boxed technical investigation that produces a findings document with clear recommendations.
Arguments
$ARGUMENTS - Required: the question, hypothesis, or topic to investigate
Context
- Project type: !
find . -maxdepth 1 \( -name go.mod -o -name Gemfile -o -name package.json -o -name Cargo.toml -o -name pyproject.toml -o -name CLAUDE.md -o -name AGENTS.md \) 2>/dev/null | head -10
- Directory structure: !
find . -maxdepth 2 -type d -not -path './.git/*' -not -path './node_modules/*' -not -path './vendor/*' 2>/dev/null | head -30
- Recent commits: !
git log --oneline -10 2>/dev/null | head -10
- Prior spikes: !
find .context/spikes -name "*.md" 2>/dev/null | head -10
Instructions
Step 1: Define the investigation
Parse $ARGUMENTS to extract:
- Question: What are we trying to answer?
- Hypothesis: What do we expect to find? (if applicable)
- Scope: What parts of the codebase or external resources are relevant?
IF $ARGUMENTS is empty or unclear, ask the user to clarify before proceeding.
Present the investigation scope and ask for confirmation:
**Question:** <parsed question>
**Hypothesis:** <if any>
**Scope:** <files, directories, or external resources to examine>
**Boundaries:** Max 50 files, 4 directory levels deep
Step 2: Investigate
Explore the codebase and relevant resources systematically:
- Read existing code — Search for relevant files, functions, and patterns. Use Glob and Grep to find related code.
- Trace dependencies — Follow imports, function calls, and data flow.
- Check prior art — Look at recent commits and prior spikes for related work.
- Prototype if needed — Write small test scripts or code samples to validate assumptions. Keep prototypes minimal.
Track findings as you go. After each round of investigation, assess:
- Did this round produce new insights?
- Are there remaining unknowns?
IF 3 consecutive investigation rounds produce no new findings, move to Step 3 with what you have.
Step 3: Write findings document
Create the findings document at .context/spikes/<date>-<slug>.md where <date> is today in YYYY-MM-DD format and <slug> is a short kebab-case summary.
Ensure .context/spikes/ directory exists first (create if needed).
Use this format:
# Spike: <title>
**Date:** <YYYY-MM-DD>
**Question:** <what we investigated>
**Status:** Complete
## Summary
<2-3 sentence executive summary of findings and recommendation>
## Background
<current state, why this investigation was needed, any prior art>
## Findings
### <Finding 1 heading>
<detailed findings with code references, file paths, and evidence>
### <Finding 2 heading>
<more findings>
## Recommendation
<clear recommendation based on , , >
High / Medium / Low
S / M / L / XL
[ ]
[ ]
Step 4: Report
Print the findings summary and the file path where the full document was saved. Offer to:
- Print the full document
- Copy to clipboard
