Spike Document Guide: Research Before You Build

3/3/2026·View as Markdown

Background #

When building software features, we often face technical unknowns or unfamiliar technologies. Jumping straight into implementation without proper research can lead to costly mistakes and rework later. This is where spike tickets come in handy.

I learned about spike tickets in 2021 at Okadoc from our product manager and scrum master. When the product team proposed new features, developers would investigate cross-system impacts and provide T-shirt sized estimates¹, letting leads review asynchronously even when they were busy with other teams. This taught me two things: spikes are collaborative, not solo activities, and they’re also commonly called “Technical Discovery” tickets.

The Why and How of Spiking #

A spike ticket (often called “Technical Discovery”) is a focused effort to replace ambiguity with data. Instead of jumping into a feature with a “best guess,” you use this time to evaluate multiple solutions and identify potential blockers when they are still cheap to fix.

To keep spikes effective, they must be strictly time-boxed, typically between one and five days. The goal is learning rather than building production-ready code. The final deliverable is knowledge: documentation, proof-of-concepts, and actionable recommendations that provide a clear implementation path.

What I Get from a Spike Document #

For me, a spike document provides a set of deliverables that helps me transition from research to implementation:

• Technical Approach Document: Details the chosen architecture and the rationale behind it.
• Task Breakdown & Estimates: Actionable tasks identified with dependencies and T-shirt sizes (S, M, L).
• Proof of Concept (PoC): Experimental code used to validate the approach. I find that investing in a good local development environment (using VMs² or a local Kubernetes cluster³) allows for much faster iteration when building these PoCs.
• Architecture Diagrams: Visual representations of system components and data flows.
• Risk Assessment: Highlights potential blockers and suggests mitigation strategies.

Example Spike Document #

To illustrate how this works in practice, here is an example of what a finished spike document might look like for a new rate-limiting service:

# [Feature Name] Spike Document

## 1. Background
We need a rate-limiting service to protect our public API from abuse. Currently, we have no global rate limiting, and spikes in traffic from a single IP can affect performance for all users.

## 2. Current State
Our API currently runs on a single node without any middleware for limiting requests. We have Redis available in our cluster, which we currently use for session storage.

## 3. Proposed Solution
Implement a sliding-window rate limiter using Redis. This approach is more efficient than a simple fixed-window counter and is well-supported by the `node-rate-limiter-flexible` package.

## 4. Task Breakdown

| Task | Backend | Frontend | Size |
|------|---------|----------|------|
| Setup Redis Rate Limiter middleware | Configure Redis connection and middleware | N/A | S |
| Create custom 429 Error Handler | Return structured JSON with `Retry-After` header | Display "Too many requests" alert | S |
| Add bypass for internal IPs | Implement IP whitelist logic | N/A | S |

## 5. Open Questions
- [Product] Should we provide different rate limits for authenticated vs. guest users?
- [Team Feedback] Are there any specific API endpoints we should exclude from global limits?
- [Risk Assessment] Is there a risk of Redis becoming a single point of failure for our API if the rate limiter is misconfigured?

What Works for Me So Far #

Beyond the standard rules of time-boxing and disposable code, I’ve found that the most successful spikes are those that stay focused and collaborative. It is vital to define success criteria before you begin. Know exactly what information you need to make a decision; otherwise, you’ll just keep researching forever.

Once the investigation is done, document everything clearly. A spike is a knowledge deliverable for the entire team, not just for you. Share the document early and invite feedback from relevant teams—like Product for business requirements or Engineering for technical validation—to build shared confidence. When it’s time to move to implementation, start with a clean slate; don’t try to refactor your experimental spike code into production.

What to Avoid #

Even with the best intentions, spikes can sometimes go off track:

• Spiking what you already know: If the team has enough info, skip the spike and choose.
• Unlimited timeboxes: Without a hard limit, you’ll spend a week on research that could have taken a day.
• Skipping peer review: Research in isolation ignores collective knowledge and misses the chance to get early feedback and agreement from relevant teams like Product or Engineering.
• Writing production code: Remember, the goal is learning, not building. Keep it experimental.

Conclusion #

Spike tickets are for building knowledge, not features. Keep them time-boxed, focused, and, most importantly, reviewed by peers.

For me, spikes give confidence when facing several unknowns. They help reduce uncertainty bit by bit, so when it’s time to implement, you’re tackling a problem you understand rather than guessing in the dark.