tp-spike

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

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

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

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

4. 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.

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