PRP Spike

Arguments: $ARGUMENTS (and $1, $2, ...) refer to the arguments given when this skill was invoked. Take them from the user's request; if absent, infer them from the conversation.

PRP Spike — Prove or Disprove

Settle an open question by building the smallest thing that could prove it wrong. The deliverable is a verdict backed by evidence, not shippable code.

Input: $ARGUMENTS (if absent, take the question from the conversation).

When to use

• Feasibility — can this be built at all, here, with what we have?
• Fit — does this sit naturally in our stack, or fight it the whole way?
• Cost of admission — what would have to change (a primitive, an abstraction, a product constraint) to make it possible, and is that trade worth it?
• Choice — which of several approaches survives contact with the real constraints?

Not for work whose feasibility is already settled — that is prp-plan then prp-implement. Not for something already broken — that is prp-debug.

The contract

1. A spike answers one falsifiable question — or several sub-claims that share a single falsifier. No falsifiable question, no spike.
2. Kill criteria are written before the build. Deciding what counts as failure after seeing results turns a spike into a rationalization.
3. DISPROVEN is a success. It bought a decision with evidence and closed a path that would otherwise have cost weeks.
4. Spike code is throwaway by construction and never opens a PR.

Phase 1 — Frame

Convert the request into a claim that can fail, and fix the kill criteria before touching code.

Reconnaissance before framing is allowed, and usually required. A hypothesis that names a version, a field, a threshold, or a mechanism cannot be written cold — read the issue, the source, and the environment until the claim can be stated precisely. The line is the falsifier: never let findings produced by the thing built to test the claim reshape the claim. Recon sharpens the question; results must only answer it.

Produce four things:

• Hypothesis — one sentence, falsifiable, specific enough that two people would agree on whether it held.
• Slug — 2–4 lowercase hyphenated words from the hypothesis. It names the branch, the worktree, and the report file; derive it once here and reuse it everywhere.
• Kill criteria — the specific observations that would end this as DISPROVEN, fixed now rather than after results exist.
• Boundaries between verdicts — what separates PROVEN from CONDITIONAL, and CONDITIONAL from DISPROVEN. The kill criteria say what failure looks like; this says which kind of failure it is. Deciding that boundary after seeing results is how CONDITIONAL gets rounded to whichever verdict is more convenient.

Split on the falsifier, not the claim count. Sub-claims one artifact can test together are one spike — build it once, list them in the frame, and report a verdict per sub-claim, because the mix is the output. Sub-claims each needing their own setup are separate spikes: take the riskiest first here, and list the rest in the report's Recommendation as follow-up spikes. For the framing craft (vague-to-falsifiable rewrites, constraint questions, splitting, sizing), read references/framing.md.

If the spike compares approaches, read references/evidence.md → Fair comparison now. The winning metric must be fixed and recorded here, before either variant exists — a metric chosen afterwards will be the one the favourite happens to win.

State the frame back to the user. When running interactively, confirm an ambiguous hypothesis before building — a spike that answers the wrong question is total waste, and framing is the cheapest thing to correct. When running unattended, record the interpretation chosen and the alternatives rejected, and proceed.

Record the frame before building

Pre-commitment only counts if it outlives the conversation. Write the frame to disk now — a transcript does not survive compaction, and an agent that has seen its results can reconstruct criteria that flatter them.

# --- PRP store resolver (canonical; keep byte-identical across skills) ---
# Adopt the store that already records this root; mint a key only when none does.
_gd="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
case "$_gd" in */.git) _root="${_gd%/.git}" ;; "") _root="$PWD" ;; *) _root="$_gd" ;; esac
_root="$(cd "$_root" && pwd -P)"
_name="$(basename "$_root" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//;s/-*$//')"
_home="${PRP_HOME:-$HOME/.prp}"
_hit="$(grep -lsF "\"path\": \"$_root\"" "$_home"/*/project.json 2>/dev/null | head -1)"
PRP_DIR="${_hit%/project.json}"
[ -n "$PRP_DIR" ] || PRP_DIR="$_home/${_name:-project}-$(printf %s "$_root" | git hash-object --stdin | cut -c1-8)"
mkdir -p "$PRP_DIR"; [ -f "$PRP_DIR/project.json" ] || printf '{"path": "%s", "name": "%s"}\n' "$_root" "${_name:-project}" > "$PRP_DIR/project.json"
mkdir -p "$PRP_DIR/spikes"

The resolver keys off the main repo, so the file lands in the shared store and stays readable from the main checkout while the spike branch is untouched.

Read templates/spike-report.md now (mandatory) and create $PRP_DIR/spikes/spike-<slug>.md with its header, ## The question section, and **Verdict**: (pending). Phase 6 fills in the rest; the hypothesis, kill criteria, and verdict boundaries recorded here are never edited after this point. The pending marker keeps an abandoned spike visibly unfinished instead of reading as a report with a missing verdict.

GATE: the file exists and contains the hypothesis, kill criteria, and verdict boundaries. Do not build without it.

Phase 2 — Isolate

Spike code is disposable and often invasive. Keep it away from the working checkout.

If already in an isolated worktree — spawned there by an orchestrator — stay put and do not nest a second one. EnterWorktree is unavailable to a pinned agent; where a branch name is wanted, plain git switch -c spike/<slug> inside the current worktree is enough.

Otherwise create a worktree on a branch named spike/<slug> with git worktree add -b spike/<slug> .worktrees/spike-<slug> origin/<base>, where <base> is the repository's integration branch, and work there. A spike branch is never merged.

--here skips isolation entirely — use it only when a fresh checkout cannot run the project (gitignored build prerequisites, an expensive bootstrap, a running local stack). Record in the report that it was used and why, and leave the checkout as it was found.

Phase 3 — Research

Read only enough to choose a credible approach — one a competent engineer would defend. A spike that fails because of a naive approach has proven nothing about the idea.

• Prefer primary sources: official docs, the dependency's actual source, specs, the codebase itself.
• Use web-researcher for anything outside the training cutoff, and codebase-analyst to learn how the relevant subsystem really works before assuming what it allows.
• Stop when the approach is defensible. Research is not the deliverable here; the build is.

Phase 4 — Build the falsifier

Build the smallest artifact that could prove the hypothesis wrong, then stop.

The shape follows the question, not a catalogue — an interactive demo, a comparison of N implementations against a stated metric, a probe against a real API, a load harness, a type-level sketch, a patched dependency proving a primitive change works. Ask: what would I have to see to stop believing this? Build that.

Hold to:

• Aim at the risk. Build the part that might fail. Scaffolding, auth, styling, and persistence are not the question — stub them.
• No production habits. No tests, no error handling beyond what keeps it running, no abstractions. Every hour spent making spike code good is an hour not spent learning.
• Real inputs. Real data shapes, real API, real volumes. A spike on synthetic happy-path data proves nothing about production.
• Surface the state. Print or render what the artifact is doing, so the evidence is observable rather than asserted.
• Track what got faked. Every stub is a hole in the proof; the report has to name them.

Phase 5 — Stress

A spike that only ran the happy path has not been tested — it has been demoed. Attack the claim where it is weakest.

Work the kill criteria from Phase 1 deliberately: push the volume, break the assumption the approach rests on, feed the edge case, pull the dependency. Most spikes earn their keep here.

For evidence standards — what counts as proof, how to make a comparison fair, and the traps that make spikes lie — read references/evidence.md.