Run Spike

Run Spike

A run-spike is throwaway code whose only job is to answer one design question. The question decides the shape.

Pick a branch

Identify the question first — from the request, the surrounding code, or by asking:

• "Does this logic / state model hold up?" → LOGIC.md: an interactive terminal app over a pure logic module the user can drive by hand.
• "What should this look like?" → REQUIRED SUB-SKILL: use draft-ui — the UI branch is that skill now: divergent real-HTML variants behind a switcher, a review loop, and a locked ui-brief. UI.md is a pointer.

Picking the wrong branch wastes the whole run-spike. If it's genuinely ambiguous and the user is unreachable, choose by proximity (backend module → logic; page or component → UI) and record the assumption at the top of the run-spike.

Rules for the logic branch

1. Throwaway from day one, and marked as such. Put it near the code it's exploring so context is obvious, but name it so nobody mistakes it for production (run-spike in the path or filename). Follow the project's existing conventions — never invent new top-level structure for it.
2. One command to run. Register it with the project's existing task runner (read commands from docs/agents/project.md when present). The user starts it without thinking.
3. No persistence. State lives in memory. Persistence is what the run-spike is testing an idea against, not something it depends on. If the question is explicitly about storage, use a scratch store with an unmistakable "run-spike — safe to wipe" name.
4. Skip the polish. Write the logic inline, hardcoded, in the fewest lines that answer the question — no tests, and only enough error handling to keep it runnable. Speed of learning is the whole point.
5. Surface internal state. After every action, show the full relevant state. Hidden state hides the answer.
6. Delete or absorb when done. Once the question is answered, remove the run-spike or fold the validated piece into real code — REQUIRED SUB-SKILL: use test-first when reimplementing it as production code; the run-spike's logic is a reference, not tested code.

The answer is the only deliverable

Nothing about the run-spike's code matters afterward — only what it taught you. Capture the question and its answer somewhere durable: an ADR (if it clears the ADR gate in define-domain), a requirement in the feature's requirements.md, or the commit message that deletes/absorbs the run-spike. If the user isn't around to give the verdict, leave a clearly-marked placeholder for it next to the run-spike so it gets filled in before deletion.