Defining Spikes

Overview

Transform underdefined feature requests into structured spike definitions that multiple agents can execute in parallel, each exploring a different approach.

Core principle: Define once, execute many times. The definition creates a contract for parallel exploration.

Announce at start: "I'm using the Defining Spikes skill to create a spike definition."

What is a Spike Definition?

A spike definition is NOT implementation. It's a structured exploration plan containing:

Clear goal and success criteria
Canonical identifier for branches/files
2-3 genuinely different approaches to try
Git infrastructure for parallel execution

You are defining what to explore, not exploring it yourself.

The Process

Copy this checklist to track progress:

Defining Spikes Progress:
- [ ] Phase 1: Understanding Desired Outcome (goal and success criteria gathered)
- [ ] Phase 2: Implementation Constraints (must-haves/must-nots identified or skipped)
- [ ] Phase 3: Choose Canonical Name (kebab-case identifier confirmed with partner)
- [ ] Phase 4: Generate Approaches (2-3 genuinely different approaches listed)
- [ ] Phase 5: Create Spike Infrastructure (branch, notes file committed)

Phase 1: Understanding Desired Outcome (Mandatory - ONE round)

Ask 1-4 questions focused on WHAT, not HOW:

Ask about:

What problem are we solving?
What does success look like?
What constraints exist (backwards compatibility, performance, security)?
How will we know we're done?

Don NOT ask about:

Which library to use
How to architect it
Implementation details
Specific technical approaches

One round only. Get enough to understand the goal, then move forward.

Phase 2: Implementation Constraints (Optional - ONE round if needed)

Only ask if there are unclear must-haves or must-nots:

"Must use existing auth system"
"Can't add new dependencies"
"Must support IE11"

If partner didn't mention constraints, assume none. Move to Phase 3.

Phase 3: Choose Canonical Name

Create short kebab-case identifier. Examples:

replace-3d-vectors
add-graphql-api
improve-test-perf
migrate-to-postgres

Ask partner to confirm the name. This name will be used for all branches and files.

Phase 4: Generate Approaches

List 2-3 numbered, high-level approaches that are genuinely different.

Genuinely different means:

Different strategies, not just different libraries
Different architectural patterns
Different scope or migration paths

Examples:

✅ Good - Genuinely Different:

1. Incremental migration with parallel APIs
2. Gateway/facade pattern wrapping existing system
3. Full rewrite with shared business logic

❌ Bad - Too Similar:

1. Use date-fns library
2. Use Day.js library
3. Use Luxon library

(These are all "adopt a library" - same strategy)

If no obvious different approaches exist, say so:

Approaches:
- Only one obvious approach: [describe it]

Phase 5: Create Spike Infrastructure

Create branch: spike-[canonical-name]
Determine spike notes location (use bash test -d docs to check):
- If docs/ directory exists: create docs/spike-notes-[canonical-name].md
- If docs/ does not exist: use AskUserQuestion tool to ask partner:
  - Option 1: Create docs/ directory and use it
  - Option 2: Write spike-notes-[canonical-name].md to project root
DO NOT:
- Create alternative directories like .spikes/, spikes/, etc.
- Create subdirectories like docs/spikes/
- Invent custom organization structures
- Use symlinks or other indirection
Use ONLY docs/ (if exists or created) OR project root.
Create file: spike-notes-[canonical-name].md (in determined location) with this structure:

# Spike: [Canonical Name]

## Goal
[What we're trying to achieve]

## Success Criteria
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
- [ ] [Measurable outcome 3]

## Constraints
[Must-haves and must-nots, or "None"]

## Approaches

### Approach 1: [Name]
[High-level description]

### Approach 2: [Name]
[High-level description]

### Approach 3: [Name]
[High-level description - if applicable]

## Effort Limit
[e.g., "~2-3 hours of exploration per approach"]

## Notes
[Any additional context]

Commit spike notes to the spike branch
Tell partner: "Spike defined. Ready to execute with branches like spike-[canonical-name]-1, spike-[canonical-name]-2, etc."

Red Flags - STOP and Reconsider

Planning implementation details → You're executing, not defining
Creating WIP branch to start coding → You're executing, not defining
Creating custom spike directories (.spikes/, spikes/, etc.) → Use docs/ or project root only
Asking many rounds of questions → Limit to 2 rounds max
"I need more information before I can start" → Start with what you have
"20 minutes isn't enough time" → Time pressure is not an excuse to skip steps
Accepting vague success criteria → Pin down "what does done look like?"

All of these mean: You're not following the defining-spikes process.

Common Rationalizations

| Excuse | Reality | |--------|---------| | "Too open-ended to define" | That's what spikes are for - reducing ambiguity | | "I need to explore the codebase first" | That's execution, not definition | | "This is too simple for multiple approaches" | Then say so explicitly - don't assume | | "Time pressure - skip the git setup" | Git infrastructure is mandatory, even under pressure | | "Let me just implement it" | You're defining, not executing |

When NOT to Use This Skill

Don't use for:

Well-defined features (use writing-plans instead)
Questions that don't need exploration (just answer them)
Single obvious approach (may not need a spike at all)

Ask partner: "This seems well-defined. Do you actually want a spike, or should we plan the implementation directly?"

After Definition Complete

Your job is done. Partner will either:

Execute spikes themselves
Spawn multiple agents to execute approaches in parallel
Decide a spike isn't needed after seeing the definition

Do NOT start implementing. Definition and execution are separate roles.

Remember

2 rounds of questions maximum
Focus on WHAT, not HOW
Get canonical name approval
Generate genuinely different approaches (or note if only one exists)
Create git infrastructure (branch + committed notes file)
Pin down success criteria
Then STOP - don't implement