Spike Skill: Validate Ideas with Throwaway Experiments

The Spike skill is for the moments before you commit to a build, when the only honest way to answer "is this even possible?" is to try it. It turns a vague idea into a small, disposable experiment that produces observable evidence, then throws that experiment away. Reach for it when you want to compare two libraries, prove a risky assumption, or surface unknowns that reading docs cannot resolve.

What it does

A spike is a structured, time-boxed experiment. Instead of guessing whether an approach works, you decompose the idea into a few independent feasibility questions, research each one just enough to pick a direction, build a minimal prototype, and record a verdict. The output is not production code; it is a decision aid. Each spike lives in its own directory with a README that captures the question, the approach, the results, and a clear verdict: VALIDATED, PARTIAL, or INVALIDATED.

The skill enforces a loop: decompose, research, build, verdict, then iterate on findings. That loop keeps the experiment honest and prevents the common failure of declaring success after one happy-path run.

Before you start

This skill is bundled with Hermes Agent, so it is installed by default. It runs on linux, macos, and windows. There are no special permissions or additional installs required for the standalone version. If you have the full GSD system installed, a sibling skill named gsd-spike may be available; prefer that one when you want persistent spike state and MANIFEST tracking. This skill is the lightweight alternative for everyone else.

Core method

Every spike, regardless of scale, follows the same loop:

decompose  →  research  →  build  →  verdict
   ↑__________________________________________↓
                  iterate on findings

1. Decompose

Break the user's idea into 2-5 independent feasibility questions. Each question becomes one spike. Present them as a table with Given/When/Then framing:

#	Spike	Validates (Given/When/Then)	Risk
001	websocket-streaming	Given a WS connection, when LLM streams tokens, then client receives chunks < 100ms	High
002a	pdf-parse-pdfjs	Given a multi-page PDF, when parsed with pdfjs, then structured text is extractable	Medium
002b	pdf-parse-camelot	Given a multi-page PDF, when parsed with camelot, then structured text is extractable	Medium

Spike types:

standard, one approach answering one question
comparison, same question, different approaches (shared number, letter suffix a/b/c)

Good spike questions: specific feasibility with observable output. Bad spike questions: too broad, no observable output, or just "read the docs about X".

Order by risk. The spike most likely to kill the idea runs first. No point prototyping the easy parts if the hard part doesn't work.

Skip decomposition only if the user already knows exactly what they want to spike and says so. Then take their idea as a single spike.

2. Align (for multi-spike ideas)

Present the spike table. Ask: "Build all in this order, or adjust?" Let the user drop, reorder, or re-frame before you write any code.

3. Research (per spike, before building)

Spikes are not research-free, you research enough to pick the right approach, then you build. Per spike:

Brief it. 2-3 sentences: what this spike is, why it matters, key risk.
Surface competing approaches if there's real choice:

Approach	Tool/Library	Pros	Cons	Status
...	...	...	...	maintained / abandoned / beta

Pick one. State why. If 2+ are credible, build quick variants within the spike.
Skip research for pure logic with no external dependencies.

Use Hermes tools for the research step:

web_search("python websocket streaming libraries 2025"), find candidates
web_extract(urls=["https://websockets.readthedocs.io/..."]), read the actual docs (returns markdown)
terminal("pip show websockets | grep Version"), check what's installed in the project's venv

For libraries without docs pages, clone and read their README.md / examples/ via read_file. Context7 MCP (if the user has it configured) is also a good source, mcp_*_resolve-library-id then mcp_*_query-docs.

4. Build

One directory per spike. Keep it standalone.

spikes/
├── 001-websocket-streaming/
│   ├── README.md
│   └── main.py
├── 002a-pdf-parse-pdfjs/
│   ├── README.md
│   └── parse.js
└── 002b-pdf-parse-camelot/
    ├── README.md
    └── parse.py

Bias toward something the user can interact with. Spikes fail when the only output is a log line that says "it works." The user wants to feel the spike working. Default choices, in order of preference:

A runnable CLI that takes input and prints observable output
A minimal HTML page that demonstrates the behavior
A small web server with one endpoint
A unit test that exercises the question with recognizable assertions

Depth over speed. Never declare "it works" after one happy-path run. Test edge cases. Follow surprising findings. The verdict is only trustworthy when the investigation was honest.

Avoid unless the spike specifically requires it: complex package management, build tools/bundlers, Docker, env files, config systems. Hardcode everything, it's a spike.

Building one spike, a typical tool sequence:

terminal("mkdir -p spikes/001-websocket-streaming")
write_file("spikes/001-websocket-streaming/README.md", "# 001: websocket-streaming\n\n...")
write_file("spikes/001-websocket-streaming/main.py", "...")
terminal("cd spikes/001-websocket-streaming && python main.py")
# Observe output, iterate.

Parallel comparison spikes (002a / 002b), delegate. When two approaches can run in parallel and both need real engineering (not 10-line prototypes), fan out with delegate_task:

delegate_task(tasks=[
    {"goal": "Build 002a-pdf-parse-pdfjs: ...", "toolsets": ["terminal", "file", "web"]},
    {"goal": "Build 002b-pdf-parse-camelot: ...", "toolsets": ["terminal", "file", "web"]},
])

Each subagent returns its own verdict; you write the head-to-head.

5. Verdict

Each spike's README.md closes with:

## Verdict: VALIDATED | PARTIAL | INVALIDATED

### What worked
- ...

### What didn't
- ...

### Surprises
- ...

### Recommendation for the real build
- ...

VALIDATED = the core question was answered yes, with evidence. PARTIAL = it works under constraints X, Y, Z, document them. INVALIDATED = doesn't work, for this reason. This is a successful spike.

Comparison spikes

When two approaches answer the same question (002a / 002b), build them back to back, then do a head-to-head comparison at the end:

## Head-to-head: pdfjs vs camelot

| Dimension | pdfjs (002a) | camelot (002b) |
|-----------|--------------|----------------|
| Extraction quality | 9/10 structured | 7/10 table-only |
| Setup complexity | npm install, 1 line | pip + ghostscript |
| Perf on 100-page PDF | 3s | 18s |
| Handles rotated text | no | yes |

**Winner:** pdfjs for our use case. Camelot if we need table-first extraction later.

Frontier mode (picking what to spike next)

If spikes already exist and the user says "what should I spike next?", walk the existing directories and look for:

Integration risks, two validated spikes that touch the same resource but were tested independently
Data handoffs, spike A's output was assumed compatible with spike B's input; never proven
Gaps in the vision, capabilities assumed but unproven
Alternative approaches, different angles for PARTIAL or INVALIDATED spikes

Propose 2-4 candidates as Given/When/Then. Let the user pick.

Output

Create spikes/ (or .planning/spikes/ if the user is using GSD conventions) in the repo root
One dir per spike: NNN-descriptive-name/
README.md per spike captures question, approach, results, verdict
Keep the code throwaway, a spike that takes 2 days to "clean up for production" was a bad spike

When not to use it

The source is explicit about when to skip this skill. If the answer is knowable from docs or reading code, just do research, do not build. If the work is production path, use the plan skill instead. If the idea is already validated, jump straight to implementation. Spikes are for genuine uncertainty, not for avoiding research or for building something you intend to keep.

Limits and gotchas

The biggest gotcha is treating a spike as the start of production code. The skill warns that a spike taking two days to clean up was a bad spike. Another trap is declaring victory after a single happy-path run; the verdict is only trustworthy when you tested edge cases and followed surprises. Also, avoid pulling in heavy tooling: complex package management, build tools, Docker, env files, and config systems are all discouraged unless the spike specifically requires them. Hardcode everything.

What pairs with this

The source lists three related skills: sketch, subagent-driven-development, and plan. Use sketch for an even earlier, lighter exploration. Use plan when the idea is validated and you are ready to design the production path. Use subagent-driven-development when you want to delegate the actual build after the spike answers the feasibility question.

Attribution

Adapted from the GSD (Get Shit Done) project's /gsd-spike workflow, MIT © 2025 Lex Christopherson (gsd-build/get-shit-done). The full GSD system offers persistent spike state, MANIFEST tracking, and integration with a broader spec-driven development pipeline; install with npx get-shit-done-cc --hermes --global.