# Run Spike

> Use when a design question needs a runnable answer — the user wants to run-spike, spike, or mock up a state model or piece of logic to feel out whether it holds up, or to see what a screen could look like, before committing to a real implementation.

- Skill: `jayden-dang/run-spike` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add jayden-dang/run-spike`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jayden-dang/run-spike/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: jayden-dang (https://skillmd.com/u/jayden-dang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jayden-dang/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](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](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.