spike-prototype
verifieda37976ba-a09b-4c61-8771-7eaeb574d2f0
Run a timeboxed throwaway experiment to de-risk an unknown (a library, an API, a perf question) before committing to an architecture. Use when you don't know whether an approach will work.
Metadata
Skill file
# Spike Prototype
Use when you do not know whether an approach will work — an unfamiliar library, an
API whose behavior is unclear, a performance question, a schema migration risk. A
spike is a **timeboxed throwaway experiment** whose deliverable is a *decision with
evidence*, not code to merge.
## 1. Timebox discipline
Set a hard deadline *before* you start and write it down. The output is a decision;
once the clock runs out, you write up what you know and stop, even if you did not
fully solve the problem.
```text
Spike: Can SQLite WAL mode handle 500 concurrent readers?
Timebox: 60 minutes, hard stop at 17:00.
Question: does read throughput degrade past 200 connections?
```
Common timeboxes:
- Library/API feasibility: 30–60 min
- Performance/scaling question: 60–90 min
- Data-migration risk: 45 min
## 2. What to capture (the write-up)
At the end, write a short note containing all five parts — this *is* the deliverable:
1. **What worked** — the concrete thing that succeeded, with the command/output.
2. **What failed** — every dead end, so the next person does not re-explore it.
3. **Exact commands run** — copy-pasteable, so results are reproducible.
4. **Recommendation** — go / no-go / need-more-info.
5. **Confidence level** — high / medium / low, with one reason.
```markdown
## Spike: SQLite WAL concurrency
- Worked: `PRAGMA journal_mode=WAL` sustained 480 readers; reads did not block.
- Failed: 600+ readers hit "database is locked" on writes (single-writer limit).
- Commands: `sysbench --test=fileio ...` then `wrk -t4 -c500 ...`.
- Recommendation: GO for read-heavy service; cap writes or shard for write-heavy.
- Confidence: medium — tested locally, not on prod hardware.
```
## 3. Isolating the spike
Never run a spike in the main tree. Use one of:
```bash
# Option A: a scratch branch (deletable, never merged)
git checkout -b spike/sqlite-wal
# Option B: a throwaway dir outside the repo
mkdir -p /tmp/spike-sqlite && cd /tmp/spike-sqlite
# Option C: a single script you can delete
python -c "import sqlite3; ..." # or a tmp file
```
Rule: the spike must be **deletable without `git rm`** in the real codebase. If you
find yourself writing production-shaped code, stop — you are no longer spiking.
## 4. When the spike ends
- Timebox expires → write the note, delete the scratch branch/dir.
- You hit a clear yes/no → write the note with the evidence, stop early.
- You are still uncertain → record "need more info" and name *exactly* what would
resolve it (a specific follow-up experiment or question).
## 5. Types of spikes
Not every unknown is answered by "write some throwaway code." Match the spike type
to the question, and state the type in the spike header so the reader knows what
"success" means.
| Spike type | Question it answers | Typical output |
|---|---|---|
| **Library feasibility** | "Does this library do X well enough?" | A working toy + go/no-go |
| **API exploration** | "What does this endpoint actually return/require?" | Recorded request/response pairs |
| **Performance** | "Does it scale to N req/s with this approach?" | Benchmark numbers + threshold verdict |
| **Data/migration** | "Can we migrate this data safely?" | A dry-run migration + row counts |
| **Integration** | "Do these two systems interoperate?" | Minimal end-to-end wiring |
## 6. Spike vs prototype vs PoC
These are conflated constantly; they have different deliverables and fates:
| Term | Deliverable | Fate |
|---|---|---|
| **Spike** | A decision + evidence (throwaway code) | Deleted after the decision |
| **Prototype** | A working approximation to validate a design | Discarded or re-implemented |
| **PoC** | The thinnest *real* implementation proving viability | May evolve into the real thing |
The rule "never merge the spike" applies strictly to spikes. A PoC that evolves
into production is a different, deliberate choice — just make that choice explicitly
rather than by accident.
## Guardrails
- Do **not** let the spike silently become production code. If the spike result is
"go", re-implement it properly (typed, tested, reviewed) in the real tree.
- Do **not** skip the write-up. An unrecorded spike is a wasted spike.
- Do **not** timebox so short that the result is uninformative (a 10-minute "it
maybe works" tells you nothing).
- Do **not** run the spike against production data or services without a sandbox.
- Delete the scratch branch/dir after the decision; do not leave `spike/*` cruft.
## Pitfalls
- **Spike becomes prod code** — the classic: you merge the throwaway because it
"mostly works", inheriting missing tests and hacks.
- **Timeboxing too short** — a result too thin to base a decision on is worse than
no spike.
- **No evidence in the write-up** — "it seemed fine" is not a recommendation with
confidence; the commands + output are the point.
- **Spiking the wrong question** — a spike that answers "is it fun to use" instead
of "does it scale / does it integrate" de-risks nothing.
- **Leaving the scratch behind** — orphan `spike/` branches and `/tmp` dirs confuse
the next reader.
## Verify / Checklist
- [ ] A hard timebox was set and written down before starting.
- [ ] The spike ran in a scratch branch or `/tmp`, never the main tree.
- [ ] The write-up has all five parts: worked, failed, commands, recommendation, confidence.
- [ ] Commands are copy-pasteable and reproducible.
- [ ] A go/no-go/need-more-info decision is stated, not left implied.
- [ ] Scratch branch/dir is deleted after the decision.
- [ ] Any "go" result is scheduled for proper re-implementation, not merged as-is.Attached files
No attached files.