Executing Spikes

Overview

Execute one approach from a spike definition autonomously, exploring feasibility without asking permission or polishing code.

Core principle: Fast exploration over clean code. Prove it works, don't perfect it.

Announce at start: "I'm using the Executing Spikes skill to explore approach N."

Context Override Authority

This skill explicitly overrides:

• •TDD rules (skip test-first discipline, prove it works however is fastest)
• •Code quality rules (messy code is GOOD during spikes)
• •"Ask for permission" rules (make decisions autonomously, document assumptions)

These overrides are NOT permission exceptions - they are the correct behavior for spike execution.

The Process

Copy this checklist to track progress:

Executing Spikes Progress:
- [ ] Phase 1: Setup Worktree (worktree created, data stores isolated)
- [ ] Phase 2: Load Spike Definition & Choose Approach (spike notes read, approach chosen)
- [ ] Phase 3: Autonomous Exploration (implementation complete, quick-and-dirty code)
- [ ] Phase 4: Proving It Works (test script runs, output captured)
- [ ] Phase 5: Push Until Natural Stop (reached natural stopping point)
- [ ] Phase 6: Discovery Report (findings documented, work committed)

Phase 1: Setup Worktree

1. •Announce: "I'm using the Using Git Worktrees skill to set up spike workspace."
2. •Use skills/collaboration/using-git-worktrees
3. •Branch from spike-[canonical-name] creating spike-[canonical-name]-N
4. •Partner tells you which number to use (1, 2, 3...)

Data Store Isolation (Any Project with Databases/State)

CRITICAL: Each spike must use its own data stores to prevent parallel spikes from conflicting.

Applies to: PostgreSQL, MySQL, SQLite files, Redis databases, MongoDB collections, etc.

Before creating schema or running migrations, verify isolation:

For Rails projects, check both development AND test databases:

# Check what database you'll use
bin/rails db:migrate:status

# Expected: database name should be spike-specific
# ✅ Good: spike_overlay_data_model_2_development
# ✅ Good: spike_overlay_data_model_2_test
# ❌ Bad: myapp_development (shared across all spikes)

For other frameworks, verify equivalent isolation mechanism exists.

If data stores are NOT isolated:

• •STOP and implement isolation (check config for branch/worktree-based naming)
• •If you cannot figure out how to isolate data stores, STOP and ask partner for guidance before proceeding
• •Do NOT proceed with shared data stores - parallel spikes will conflict

Why critical: Without isolation, parallel spikes will drop each other's tables/collections, wasting hours debugging phantom failures that only occur when multiple spikes run simultaneously.

Phase 2: Load Spike Definition & Choose Approach

1. •Read spike-notes-[canonical-name].md from the base spike branch
2. •Copy to your worktree if needed
3. •Extract approach number from branch name
   • •Example: spike-replace-3d-vectors-2 → approach 2
4. •If that numbered approach exists in notes: use it
5. •If that numbered approach doesn't exist: Create one, document it in spike notes
6. •Document your chosen approach details

Phase 3: Autonomous Exploration

Execute independently:

• •Make ALL decisions yourself (library choices, architecture, error handling)
• •Document assumptions in spike notes
• •Quick-and-dirty over clean code
• •Duplication is fine, inconsistent naming is fine, messy code is GOOD
• •Don't stop to validate choices
• •Don't ask for permission
• •Push through minor obstacles with workarounds

Code Quality Expectations for Spikes:

• •✅ GOOD: Duplicated code across 3 places
• •✅ GOOD: Inconsistent naming
• •✅ GOOD: Quick hacks and workarounds
• •✅ GOOD: Copy-pasted code
• •✅ GOOD: Hardcoded values
• •❌ BAD: Spending time refactoring
• •❌ BAD: Extracting shared functions
• •❌ BAD: Consistent abstractions
• •❌ BAD: "Clean" code

The goal is learning speed, not maintainable code.

Phase 4: Proving It Works (Critical)

Your spike MUST actually run and do something.

Minimum requirement: Create executable test script

1. •

   Create a test file that can be run with a single command:

   • •test_spike.rb / test_spike.py / test.sh / npm run spike-test
   • •Should test ALL scenarios from spike definition
   • •Must print clear output showing pass/fail
2. •

   Run it and capture output:

   • •Don't just write the tests - RUN THEM
   • •Copy actual output into your report
   • •Output is proof you didn't just write code that "looks right"
3. •

   Test script should:

   • •Setup test data
   • •Exercise the spike's core functionality
   • •Print results for each scenario
   • •Use ✅/❌ or PASS/FAIL markers for clarity

Example test script output:

=== Testing Scenario 1: Base entity ===
✅ Loaded entity: {"name": "Bran", ...}

=== Testing Scenario 2: With overlay ===
✅ Applied overlay, got: {"name": "Bran", "items": ["mace"], ...}

=== Testing Scenario 3: Mutual exclusivity ===
✅ Validation rejected conflicting overlays
Error: "recently-bubbled and 100-years-bubbled are mutually exclusive"

Choose fastest validation method:

Quick validation (prefer these):

• •Test script that exercises all scenarios (recommended)
• •Manual testing with documented steps + output
• •Print statements showing data flow
• •Simple integration showing end-to-end works

Automated tests (use if already faster):

• •Integration tests proving happy path
• •Tests as executable documentation

TDD discipline (SKIP THIS):

• •❌ Test-first workflow
• •❌ Comprehensive coverage
• •❌ Testing edge cases exhaustively
• •❌ RED-GREEN-REFACTOR cycle

The rule: Your spike must work - run it and prove it. Use whatever validation is fastest.

Red flags:

• •❌ "The code looks correct" → Run it
• •❌ "I tested it mentally" → Run it
• •❌ "Logic is sound" → Run it
• •❌ Writing report without running code → Stop, run it first

In your report, include:

• •Path to test script
• •Command to run it
• •Full output (or representative sample if very long)
• •Mapping of output to spike test scenarios

Phase 5: Push Until Natural Stop

Stop when:

• •Feature works end-to-end and you've proven it (success!)
• •Hit genuine blocker you can't work around (missing system dependency, fundamental incompatibility)
• •Discovered approach won't work (fundamental design flaw)
• •Reasonable effort expended (~2-3 hours worth of exploration)

Don't stop when:

• •Code is messy (that's fine - this is exploratory)
• •Hit a minor error (try workaround first)
• •Unsure if approach is "right" (keep going, that's not the spike's purpose)
• •Want to check if design is okay (make the call yourself)
• •Want to refactor (skip it entirely)
• •Tests are incomplete (you're not doing TDD)

Phase 6: Discovery Report

Create a detailed spike report following the standardized template in reference/report-template.md.

Key requirements:

• •12 required sections covering implementation, results, evaluation, and next steps
• •File name: SPIKE_FINDINGS_APPROACH_N.md
• •Evidence-based: Include actual test output, not paraphrases
• •Weighted scoring: Use criteria from spike definition (if provided)
• •Proof of work: Executable test script + actual output demonstrating it works
• •Git workflow: Commit all code and report, don't push unless requested

Critical:

• •No comparisons to other spike approaches (you don't know what they did yet)
• •Include objective criteria: "Works best when X, avoid when Y"
• •Be honest about tradeoffs and limitations

See the full template for detailed structure and examples.

Autonomy: When to Ask vs When to Decide

Ask partner when:

• •Hit genuine blocker (missing system dependency, fundamental incompatibility)
• •Cannot isolate data stores and unsure how to proceed
• •Spike notes file is missing or corrupted
• •Need clarification on spike goal/constraints

Decide independently when:

• •Which library to use → Pick one, document choice
• •How to structure code → Quick-and-dirty wins
• •Whether to refactor messy code → Don't refactor
• •How to handle an error → Try workaround
• •What "good enough" looks like → Working code is enough
• •How to prove it works → Manual test vs automated test vs script
• •Library version conflicts → Use what works, document it
• •Whether to add caching/pooling/metrics → Make the call, document it
• •How thorough to be → Push until natural stop
• •TTL values, configuration, connection settings → Pick reasonable defaults
• •Database naming/isolation strategy → Implement it, document it
• •Test script format → Whatever proves it works fastest

If you're asking "Should I ask about X?" - the answer is: decide and document.

Report format questions:

• •Don't ask "Should I include X in my report?" → Follow the template
• •Don't ask "Is this enough detail?" → Template specifies what's needed
• •Do ask if template section doesn't make sense for your spike type

Red Flags - STOP and Course Correct

If you catch yourself doing these, you're NOT executing a spike correctly:

• •Asking validation questions → "Should I use library X?" → NO, decide and document
• •Refactoring messy code → "This duplication should be cleaned up" → NO, keep pushing
• •Following TDD → "Let me write the test first" → NO, prove it works however is fastest
• •Polishing code → "Let me make this cleaner" → NO, messy is good
• •Not running code → "The logic looks correct" → NO, run it and prove it
• •Seeking permission → "Is it okay to use Docker?" → NO, use it and document
• •Second-guessing scope → "Should I explore additional aspects?" → Push until natural stop

All of these mean: You're applying production standards to exploratory work.

Common Rationalizations to Resist

Completion Verification

Before reporting to your partner that the spike is complete, verify ALL of these:

Copy this verification checklist to ensure nothing was skipped:

Spike Completion Verification:

**Setup:**
- ✅ Data stores are isolated (checked with status command)
- ✅ Working in correct spike worktree
- ✅ Database/state won't conflict with other spikes

**Implementation:**
- ✅ Code actually runs (not just "looks right")
- ✅ Test script exists and executes
- ✅ Test output captured
- ✅ All spike definition scenarios tested

**Report:**
- ✅ Used standardized template (12 required sections)
- ✅ Included weighted scoring with calculation shown
- ✅ Test results map to ALL spike scenarios
- ✅ Time breakdown included
- ✅ Interface/usage design documented (if applicable)
- ✅ Evidence included for every claim
- ✅ Actual test output pasted (not paraphrased)
- ✅ No comparisons to other spike approaches
- ✅ Code quality self-assessment included

**Git:**
- ✅ All work committed
- ✅ Report file committed
- ✅ Commit message follows format

**Red Flags - Stop and Fix:**
- ❌ Report says "it works" but no test output shown
- ❌ Report compares to other approaches ("better than Approach X")
- ❌ Didn't actually run the code
- ❌ Test script doesn't exist or doesn't run
- ❌ Report missing required sections from template
- ❌ No weighted scoring calculation
- ❌ Database isolation not verified

Common New Pitfalls to Avoid

With the updated guidance, watch for these new failure modes:

When NOT to Use This Skill

Don't use for:

• •Production features (use skills/testing/test-driven-development)
• •Well-defined implementations (use skills/collaboration/executing-plans)
• •Code that will be merged as-is (spikes are throwaway exploration)
• •Learning a codebase (use exploration/research skills)

Ask partner: "Is this actually a spike, or should we build this properly with TDD?"

Related Skills

Before spike execution:

• •skills/collaboration/defining-spikes (creates the spike definition)
• •skills/collaboration/using-git-worktrees (sets up isolated workspace)

During exploration:

• •skills/problem-solving/collision-zone-thinking (if stuck in conventional thinking)

After spike:

• •skills/collaboration/requesting-code-review (if approach is viable and will be productionized)

Remember

• •Messy code is GOOD during spikes
• •Make decisions autonomously, document assumptions
• •Prove it works (run it!), don't perfect it
• •Skip TDD discipline, use fastest validation
• •Don't refactor during exploration
• •Stop at natural stopping points
• •Report with evidence ("I ran X, got Y")
• •Use standardized report template for comparability
• •Isolate data stores to avoid parallel spike conflicts