spike

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:

1. Read existing code — Search for relevant files, functions, and patterns. Use Glob and Grep to find related code.
2. Trace dependencies — Follow imports, function calls, and data flow.
3. Check prior art — Look at recent commits and prior spikes for related work.
4. 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.