Technical Spike Skill

Purpose: Conduct objective-driven technical investigations to reduce uncertainty before committing to implementation.

Philosophy: A spike is finished when the objective is reached, NOT when a time limit expires. Spikes produce knowledge artifacts, not production code.

When to use:

• Technical feasibility is unknown ("Can this library handle 50MB files in under 200ms?")
• Behavioral requirements are unclear ("Should refunds work for partial orders?")
• Architecture needs validation ("Can we scale this pattern to 10k users?")
• Root cause of complex bug is unknown
• Before making architectural decisions (uncertainty reduction)

---

Core Principles (Objective-Driven Framework)

1. The Completion Trigger

A spike is finished the moment the specific objective is reached, not when a clock runs out.

• If objective reached in 20 minutes → spike complete in 20 minutes
• If objective reached in 4 hours → spike complete in 4 hours
• If objective cannot be reached → document why, close spike

Anti-pattern: "We have 2 hours for this spike" (time-boxed approach) Correct pattern: "We'll know we're done when we can successfully..." (objective-driven)

2. The "One-Question" Rule

A spike must answer ONE high-level question.

• If second question emerges → create second spike
• Prevents scope creep
• Ensures clear success criteria

Example good question: "Can WebSockets handle our real-time collaboration needs?" Example bad question: "How should we build the entire real-time system?" (too broad, multiple questions)

3. The "Burn After Reading" Mandate

Spike code must NEVER be merged into main branch.

• Spike code is written to be read, learned from, and deleted
• Disposability enables speed
• Knowledge artifact (document) is the deliverable, not code

Enforcement:

• Create spike branches: spike/topic-name
• Never merge spike branches
• Delete branch after knowledge artifact created
• Or work in isolated directory and delete after

4. Zero Polishing

No production quality needed.

• No unit tests (unless testing IS the spike objective)
• No error handling for edge cases (unless that's what you're investigating)
• No styling (unless UI behavior is being spiked)
• Hardcode credentials, use fake data, skip validation

Rationale: Speed over quality. We're learning, not shipping.

---

Spike Types

Technical Spike (The "How")

Focus: Feasibility, architecture, performance

Trigger phrases:

• "I don't know if the technology CAN do this"
• "Will this approach scale?"
• "Can we integrate X with Y?"
• "Is this library fast enough?"

Example questions:

• "Can the XYZ library process a 50MB JSON file in under 200ms?"
• "Can we run Claude API calls in parallel without hitting rate limits?"
• "Will Qdrant handle 100k vectors with acceptable query time?"

Functional Spike (The "What")

Focus: User flow, logic, requirement clarity

Trigger phrases:

• "I don't know how the system SHOULD behave"
• "What's the right user experience?"
• "How should this edge case work?"

Example questions:

• "Should multi-step vs single-page form feel more intuitive for our users?"
• "How should refund flow behave for partial orders?"
• "What happens when user tries to delete account with active subscription?"

---

Expected Outcomes (Knowledge Artifacts)

Every spike must produce ONE of these:

1. The Verdict

Format: Definitive "Yes, this works" or "No, this is a dead end"

Example:

"✅ YES - Qdrant can handle 100k vectors with <50ms query time on our VPS specs"

"❌ NO - WebSockets disconnect every 30 seconds behind AWS ALB (need sticky sessions or different approach)"

2. The Proof of Concept (PoC)

Format: Screen recording, demo, or code snippet showing "it works"

Example:

"✅ Working prototype: Users can drag-drop files, see upload progress, get confirmation. See recording: spike-file-upload.mov. Key insight: Need to chunk large files (>10MB) or upload times out."

3. The Architecture Draft

Format: Simple diagram or list of required components

Example:

"✅ Architecture sketch: Need 3 components: (1) Upload service with chunking, (2) Background processor queue, (3) Notification system. Draft in spike-architecture.png"

4. The Bug Root-Cause

Format: Clear explanation of WHY complex error happens

Example:

"✅ Root cause identified: Race condition between React state update and WebSocket message. Happens when user sends message during reconnection. Need mutex or message queue."

---

Non-Goals (Explicitly Forbidden)

Spikes must NOT attempt to:

1. Refine estimates - Spikes remove "I don't know", but don't size work (that's planning)
2. Produce production code - If code is good enough to merge, it was a Feature Task in disguise
3. Create user documentation - Spikes produce internal knowledge only
4. Make final decisions - Spike provides data; team/architect makes decision

Test: If someone asks "Can we ship this?" and answer is yes → it's not a spike, it's a feature.

---

Spike Protocol Template

Fill in before starting spike (30 seconds):

## Spike: [One-sentence question]

**Question:** [e.g., Can we use WebSockets for real-time updates?]
**Type:** Technical | Functional
**Success Criteria:** [e.g., I have a local script that successfully echoes a message back from the server.]
**Code Strategy:** [e.g., Hardcoding all credentials; no error handling; single file script.]
**Next Step:** [e.g., Share snippet in spike doc and delete throwaway code.]

Example:

## Spike: Can Qdrant handle 100k vectors efficiently?

**Question:** Will Qdrant perform well with 100k atomic notes on our VPS specs?
**Type:** Technical
**Success Criteria:** Query time <50ms for semantic search with 100k points loaded
**Code Strategy:** Load fake data, skip authentication, hardcode config, single Python script
**Next Step:** Document query times in spike doc, delete test data, close spike

---

Spike Output Format

Location: 00 Inbox/spikes/spike-YYYY-MM-DD-topic.md

Template:

# Technical Spike: [Question]

**Type:** Technical | Functional
**Started:** [timestamp]
**Completed:** [timestamp]
**Duration:** [actual time spent]
**Objective reached:** Yes | No (with explanation)

## Question

[The one question we were trying to answer]

## Success Criteria

[What would prove the answer]

## Findings

[What we discovered - be specific, include numbers/metrics where relevant]

## Knowledge Artifact

**Type:** Verdict | PoC | Architecture Draft | Root Cause

[The concrete output from this spike]

## Recommendation

**Category:** Simple change | Moderate effort | Complex/Architectural | Dead end

[Simple next-step recommendation - NOT a detailed plan]

**If pursuing:** [Suggest creating ADR or development plan]
**If abandoning:** [Explain why, suggest alternative]

## What We Still Don't Know

[Any remaining unknowns - may trigger follow-up spike]

[If empty: "All unknowns resolved for this question."]

## Throwaway Code Location

[One of these:]
- "Deleted"
- "Branch: spike/topic-name (DO NOT MERGE)"
- "Directory: /tmp/spike-name (deleted)"
- "No code (research-only spike)"

---

Workflow

1. Define Spike Objective

• State as ONE question
• Classify as Technical or Functional
• Define clear success criteria (what proves the answer)

2. Plan Throwaway Code Strategy

• Where will code live? (branch, /tmp, isolated directory)
• What can be hardcoded? (credentials, config, fake data)
• What can be skipped? (tests, error handling, edge cases)

3. Execute Spike

• Build minimum code to answer question
• Take notes as you learn
• Stop immediately when objective reached (or determined unreachable)

4. Document Knowledge Artifact

• Write spike document using template
• Include verdict, metrics, or architecture draft
• State what we now know vs still don't know

5. Clean Up Throwaway Code

• Delete spike branch or temporary files
• Preserve only the knowledge artifact (markdown doc)
• Update spike doc with "Code deleted" confirmation

6. Make Recommendation

• Simple change → implement directly
• Moderate effort → create development plan
• Complex/Architectural → create ADR, then plan
• Dead end → document why, suggest alternatives

---

Integration with Decision-Making

Typical flow:

Uncertainty Identified
    ↓
Technical Spike (this skill)
    ↓
Knowledge Artifact Created
    ↓
Decision Point
    ├─→ Simple change? → Implement directly
    ├─→ Architectural? → Create ADR (write-adr skill)
    ├─→ Requires plan? → Create plan (create-plan skill)
    └─→ Dead end? → Document and move on

Example:

1. Technical PM identifies: "We don't know if Qdrant can scale to 100k vectors"
2. Spike conducted: Load test with fake data
3. Knowledge artifact: "Yes, <50ms query time confirmed"
4. Solutions Architect: Create ADR-003 documenting Qdrant choice
5. Development: Create PLAN-2025-XXX to implement Qdrant integration

---

Quality Checklist

Before closing spike, verify:

• One question answered - Not multiple questions
• Success criteria met - Or documented why unreachable
• Knowledge artifact created - Verdict, PoC, draft, or root cause
• Recommendation provided - Clear next step
• Throwaway code deleted - Or clearly marked as disposable
• Unknowns documented - What we still don't know (if anything)
• Spike doc complete - All template sections filled

---

Examples

Example 1: Performance Spike

Question: Can Qdrant handle 100k atomic notes with <50ms query time?

Type: Technical

Findings:

• Loaded 100k fake notes (3072-dim embeddings)
• Average query time: 23ms (p95: 41ms)
• Memory usage: 2.1GB
• CPU: <5% during queries

Verdict: ✅ YES - Qdrant performs well beyond our needs

Recommendation: Simple - proceed with Qdrant integration. Create ADR-003 to document choice.

Code: Deleted after knowledge artifact created

---

Example 2: UX Functional Spike

Question: Should account deletion be one-click or require confirmation flow?

Type: Functional

Findings:

• Built both flows in local branch
• One-click: Fast but risky (accidental deletion concern)
• Confirmation flow: Safer, shows what will be deleted
• Tested with 2 users: Both preferred confirmation (clarity on consequences)

Verdict: ✅ Confirmation flow preferred

Recommendation: Moderate - create PLAN-2025-XXX for account deletion flow with confirmation modal showing:

• What data will be deleted
• Irreversibility warning
• Final confirmation button

Code: Branch spike/account-deletion (DO NOT MERGE)

---

Example 3: Technical Feasibility (Dead End)

Question: Can we use SQLite with async Python for concurrent writes?

Type: Technical

Findings:

• SQLite locks entire database for writes
• Concurrent write attempts fail with "database is locked" error
• Read-heavy workloads OK, write-heavy fails
• Our use case: 50+ concurrent users writing data

Verdict: ❌ NO - SQLite won't work for our multi-user write pattern

Recommendation: Dead end - switch to PostgreSQL (supports concurrent writes). Create ADR-005 to document database choice.

Alternative considered: Use SQLite with write-ahead logging (WAL), but testing showed still not sufficient for 50+ writers.

Code: Deleted

---

Anti-Patterns to Avoid

1. Time-Boxing Instead of Objective-Driven

   • ❌ "We have 2 hours for this spike"
   • ✅ "We'll know we're done when we can successfully..."

2. Polishing Spike Code

   • ❌ Adding unit tests, error handling, documentation to throwaway code
   • ✅ Minimal code to prove the concept

3. Merging Spike Code

   • ❌ "This spike code is pretty good, let's just merge it"
   • ✅ "Spike proves it works. Now delete and implement properly with tests."

4. Multi-Question Spikes

   • ❌ "Let's spike authentication, authorization, and session management"
   • ✅ "Let's spike authentication approach" (separate spikes for auth and sessions)

5. Decision-Making in Spike

   • ❌ "Spike showed both work, so I chose Option A"
   • ✅ "Spike showed both work. Here's data. Solutions Architect will decide."

---

Integration Points

This skill is used by:

• technical-pm agent - Identifies uncertainties blocking estimation
• solutions-architect agent - Reduces uncertainty before architectural decisions
• Manual /spike command - User-initiated investigation

This skill spawns:

• artificial-shadow-dev - For implementation spikes
• hybrid-db-architect - For database spikes
• No agents for research-only spikes

This skill outputs to:

• write-adr skill - When spike leads to architectural decision
• create-plan skill - When spike shows moderate/complex work needed

---

Continuous Improvement

Update this skill when:

• New spike patterns emerge
• Quality issues identified in spike outputs
• Framework principles need refinement
• Integration patterns change

Document significant changes in repository CLAUDE.md.