tp-spike

name	tp-spike
description	Interactive spike design conversation that produces a spike-flavored design.md for time-boxed experiments. Optionally links back to a parent design.
argument-hint	{spike-name} [--parent {design-name}] [--force-takeover]

Spike Design

Create a spike design through conversation with the user. Spikes are time-boxed experiments to answer specific questions before committing to an implementation approach.

Arguments:

• {spike-name} (required) — kebab-case name, becomes the directory under three-pillars-docs/tp-designs/.
• --parent {design-name} (optional) — links this spike to a parent design.

Steps

0. Run first-run preflight per skills/_shared/first-run.md.

1. Validate {spike-name} per skills/_shared/validate-name.md.

2. Resolve the design directory: three-pillars-docs/tp-designs/{spike-name}/. Create it if it doesn't exist.

3. Run collaboration preflight per skills/_shared/collaboration.md with phase: "design". This verifies the branch and acquires or refreshes the lock for this spike. Honor --force-takeover if passed.

   Seat-context note: if the collaboration preflight notes that you are on the base branch ({base} / master), treat that as an affirmation — being on {base} in the resolved seat (the base checkout / worktree host) is the correct coordination point for spinning up a new spike worktree. It is not a reason to pause or seek an alternative checkout. See skills/_shared/topology.md for the canonical seat and worktree layout; the collaboration preflight's branch-check prose is unchanged.

3b. Update .claude/last-design MRU — now that the lock/branch are claimed, run the MRU snippet at the bottom of skills/_shared/validate-name.md (the bash that prepends the spike name, dedupes, caps at 10). This is the moment a subsequent /clear + /tp-session-restore (no argument) needs to resolve to this spike, not whatever was active before. The snippet handles the .gitignore append; do not git add the file. 4. Check for existing design.md. If it exists, read it and ask the user whether they want to revise it or start fresh. 5. If --parent is given, verify three-pillars-docs/tp-designs/{design-name}/design.md exists. Read it so you understand the parent context. 6. Read project context per skills/_shared/read-project-docs.md. Read three-pillars-docs/vision.md first — a spike is only worth running if answering its question would meaningfully advance or clarify the vision. If the roadmap has a ## Current Focus table, note where this spike fits relative to current priorities — mention this during the spike conversation so the user can decide its priority. 7. Vision alignment check. Before framing the hypothesis, explicitly ask: "Which vision question does this spike help answer?" If the answer is "none" — e.g. the spike explores a path the vision has declared out of scope — surface that now. The cheapest spike is the one you don't run because the vision already told you not to care about the answer. 8. Have a spike conversation. Draw out through questions:

• Hypothesis — what do we believe and want to validate? Frame it in terms of what the vision needs to know.
• Success criteria — what does GO / PARTIAL / NO-GO look like?
• Experiments — what will we try, what do we expect to observe?
• Expected demos — what artifacts (MP4s, screenshots, logs) prove findings?
• Constraints — time budget, resource limits, dependencies.
• Parent linkage — if there's a parent, what questions does this spike answer for it? Ask clarifying questions. Push back on vague hypotheses. Insist on measurable success criteria.

9. Write three-pillars-docs/tp-designs/{spike-name}/design.md with this structure:

# <Spike Name>

**Parent**: {design-name} | none
**Questions**: What this spike answers for the parent (free text)

## Hypothesis
What we believe and want to validate. 1-3 sentences.

## Success Criteria
- **GO** if: ...
- **PARTIAL** if: ...
- **NO-GO** if: ...

## Experiments
What we'll try and what we expect to observe.

## Expected Demos
What artifacts (MP4s, screenshots, logs) we'll produce to prove findings.

## Constraints
Resource limits, time budget, dependencies.

10. Register in Design Inventory: If three-pillars-docs/product_roadmap.md exists and contains a Design Inventory table, check whether {spike-name} already has a row. If not, propose appending a row with type "spike", status "Spiking", the parent design as a dependency (if any), and any other dependencies from the conversation. Show the proposed row and get user confirmation before writing. If the roadmap doesn't exist or has no Design Inventory table, skip this step silently.
11. Update Current Focus: If the roadmap has a ## Current Focus table and the user indicated this spike is a near-term priority during the conversation, propose adding it to the Current Focus table with an appropriate priority, next action (/tp-spike-plan), and any blockers. Show the proposed row and get user confirmation. If the user didn't indicate priority, ask whether it belongs in Current Focus.
12. Commit the artifacts per skills/_shared/commit-after-work.md. Artifact paths to stage:
    • three-pillars-docs/tp-designs/{spike-name}/design.md
    • three-pillars-docs/tp-designs/{spike-name}/lock.json (rolled into the same commit)
    • three-pillars-docs/product_roadmap.md (only if step 10 or 11 modified it) Commit message: Spike: {spike-name} design.
13. Tell the user the next step is /tp-spike-plan {spike-name} to create an experiment plan.

Rules

• Validate {spike-name} per skills/_shared/validate-name.md.
• Respect the lock per skills/_shared/collaboration.md — the preflight step can refuse to proceed if another developer holds this spike.
• Spikes that conflict with the vision should be refused. If a spike would explore a path that the vision's non-goals explicitly rule out, push back. The user should either drop the spike, reframe it against a vision-relevant question, or update the vision first via /tp-docs-update.
• Demo / artifact convention: every artifact a future reader of spike-results.md would want to inspect — tool inputs, tool outputs, logs, measurements, rendered media — goes in three-pillars-docs/tp-designs/<spike-name>/demos/. This directory is tracked: demos are the spike's permanent evidence record and must survive across machines, archival, and review. See the full convention in tp-spike-implement's Rules.
• Keep design.md under 60 lines. Spikes are focused, not sprawling.
• This is a conversation, not a monologue. Ask questions before writing.
• Stop after writing design.md — don't plan or implement in the same invocation.
• If --parent is specified but the parent design doesn't exist, warn the user and ask whether to proceed without a parent link.