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

1. •

   Create branch: spike-[canonical-name]

2. •

   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.

3. •

   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]

1. •Commit spike notes to the spike branch
2. •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

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