/spike — Create a Spike Ticket

Creates a structured GitHub Issue for a spike — a 1-3 day hypothesis-driven exploration whose goal is to answer a technical question with minimum investment, with the explicit understanding that the code will be discarded or substantially rewritten once the answer is clear.

When to use a spike vs a feature. If you can answer the question through reasoning alone, file a /feature. If you genuinely don't know whether an approach will work — does this library scale, does this UX make sense, will this integration handle our load — file a /spike first. The spike's output is the answer; once it's in, file a fresh [Feature] ticket with production-shaped delivery (or a memo if the answer was no). See workflows/sdlc.md § Phase 1 for the gating heuristic.

Path resolution

Read the registry path via portfolio_registry, the per-project docs dir via portfolio_projects_dir, and the ideas backlog via portfolio_ideas_backlog — all from .claude/hooks/_lib-portfolio-paths.sh. Source the helper at the top of any bash block that touches those paths:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
registry=$(portfolio_registry)

Defaults match today's single-fork layout (./apexyard.projects.yaml, ./projects, ./projects/ideas-backlog.md). Adopters in split-portfolio mode override the portfolio.{registry, projects_dir, ideas_backlog} keys in .claude/project-config.json. Don't hardcode literal apexyard.projects.yaml or projects/ paths in bash blocks — the helper resolves whichever mode the adopter is in. See docs/multi-project.md.

Usage

/spike Will library X handle 10k events/sec
/spike Does Postgres LISTEN/NOTIFY scale to N consumers
/spike Can we replace Auth0 with Cognito

Process

0. Write the active-issue-skill marker (REQUIRED — me2resh/apexyard#268)

Before any gh issue create (or other tracker CLI), write this skill's name to the active-issue-skill marker so require-skill-for-issue-create.sh lets the command through. At skill entry:

# Resolve the ops-fork root the SAME way the hooks do (_lib-ops-root.sh):
# anchor on the .apexyard-fork marker (split-portfolio v2 — onboarding.yaml
# lives in the sibling portfolio repo, NOT the ops fork), falling back to the
# onboarding.yaml + apexyard.projects.yaml pair (single-fork v1).
ops_root="$PWD"; r="$PWD"
while [ "$r" != / ]; do
  if [ -f "$r/.apexyard-fork" ] || { [ -f "$r/onboarding.yaml" ] && [ -f "$r/apexyard.projects.yaml" ]; }; then
    ops_root="$r"; break
  fi
  r=${r%/*}
done
mkdir -p "$ops_root/.claude/session"
echo "spike" > "$ops_root/.claude/session/active-issue-skill"

Remove the marker on every exit path (success, early-exit, user cancel, error):

rm -f "$ops_root/.claude/session/active-issue-skill"

The clear-issue-skill-marker.sh SessionStart hook sweeps stale markers from killed sessions, but a clean exit should never leave one behind. See AgDR-0030.

1. Resolve the target repo

Read .claude/session/current-ticket to determine which repo we're working in. If no active ticket, check apexyard.projects.yaml for managed projects. If only one project, use it. If multiple, ask:

Which project is this spike for?

If no projects are registered, ask for the repo in owner/repo format.

2. Verify the prefix is on the whitelist

Read .ticket.prefix_whitelist from .claude/project-config.*.json. If Spike (case-insensitive) is not in the list, warn and stop:

This fork's ticket schema doesn't include 'Spike' as a valid prefix.
Either add it to .claude/project-config.json → .ticket.prefix_whitelist, or
file the ticket using whichever prefix the fork uses for exploration work.

(The shipped default in .claude/project-config.defaults.json includes Spike. This check exists for forks that have customised the whitelist — see apexyard#109.)

3. Parse or ask for the title

Take the title from $ARGUMENTS. If empty, ask:

What's the spike? Give me a short title.

4. Gather details (one question at a time)

Ask conversationally — do NOT batch all questions. Wait for each answer before asking the next. The four fields below are all required; the fifth is optional.

a) Hypothesis (required)

What's the single specific question this spike answers?
Format: "We believe {X}. We will know we're right when {Y}."
(One sentence. If you can't write it that way, the spike isn't ready —
push back and ask the user to refine.)

If the user gives a casual hypothesis, restructure it into the required format and confirm.

b) Budget (required)

What's the hard cap on time/effort? Examples:
  - 2 days of one engineer
  - 1 sprint
  - Until end of week

At the budget cap, the spike ENDS regardless of outcome — that's the
commitment. What's yours?

Reject vague answers ("a while", "as long as it takes") — push for an explicit time/effort cap.

c) Kill Criteria (required)

Under what specific conditions does the spike STOP early?
(Either because the answer is in, or because pursuing further is wasted.)

Encourage at least two kill criteria — one "answered: yes" and one "answered: no / unworkable". Don't accept "we'll figure it out".

d) Disposition (required — PROMOTE or DISCARD)

What happens when the spike closes — PROMOTE or DISCARD?

  PROMOTE — if the hypothesis is confirmed, file a fresh [Feature] ticket
            with production-shaped delivery, port the relevant findings.
  DISCARD — if the hypothesis is rejected (or the answer is "we shouldn't
            do this"), delete the spike branch and file a memo with what
            we learned.

"Decide later" is NOT allowed — that's how spike code rots into half-
shipped production. Pick one.

If the user says "decide later" or "depends", explain the rule and ask again. The author must commit to one path in advance.

e) Approach (optional)

Any sketch of the exploration plan? (or press Enter to skip)
NOT a tech design, NOT a PRD — a few bullets: smallest test, tools needed,
boundary you'd cross to fail-fast.

5. Show the formatted ticket for confirmation

Resolve the spike body template via the portfolio helper so adopter overrides win when present:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
template=$(portfolio_resolve_template tickets/spike.md)   # → custom-templates/tickets/spike.md if present, else templates/tickets/spike.md

Single-fork adopters (no portfolio block) and adopters with no override fall straight through to templates/tickets/spike.md. Adopters who want a customised spike-body shape drop their version at <private_repo>/custom-templates/tickets/spike.md. See templates/README.md for the path-mirroring convention.

Backward-compat fallback: if portfolio_resolve_template returns empty (template file missing — partial adopter setup or pre-#281 layout where the file lived at templates/spike.md), fall back to the inline heredoc body below and print a one-line WARN on stderr (WARN: tickets/spike.md template missing — using inline fallback).

Display the full ticket using the resolved template's section headings (the default templates/tickets/spike.md shape is reproduced below):

Here's the ticket I'll create:

---
**[Spike] {title}**

## Hypothesis
{hypothesis}

## Budget
{budget}

## Kill Criteria
- {criterion 1}
- {criterion 2}
- ...

## Disposition
{PROMOTE | DISCARD}
{one-sentence rationale}

## Approach
{approach or "—"}
---

Labels: spike
Repo: {owner/repo}

Suggested branch when you start work:
  spike/<TICKET-ID>-{slug}

Create this ticket? (yes / edit / cancel)

6. Handle response

• yes / looks good / go → create the issue
• edit / change X → ask what to change, update, re-show
• cancel / no → abort

7. Create the issue (via the tracker abstraction)

Dispatch creation through tracker_create (#670 / AgDR-0072, extended by the #709 creator sweep) so the spike lands in this project's tracker — GitHub, GitLab, or a custom CLI — per its tracker: block in apexyard.projects.yaml. For a GitHub adopter this runs gh issue create exactly as before.

# Resolve the tracker lib (it lives in the ops fork's hooks dir) by walking up
# from the cwd; source it.
tracker_lib="$(r="$PWD"; while [ -n "$r" ] && [ "$r" != / ]; do \
  [ -f "$r/.claude/hooks/_lib-tracker.sh" ] && { echo "$r/.claude/hooks/_lib-tracker.sh"; break; }; \
  r="${r%/*}"; done)"
# shellcheck source=/dev/null
. "$tracker_lib"

# Ensure the `spike` trigger label exists on the target tracker. Best-effort
# (tracker_label_ensure always exits 0) — a duplicate/missing label never aborts
# the create. The label is what downstream hooks (AgDR-required hooks, coverage
# gates) read to apply the spike workflow exemptions.
tracker_label_ensure "{owner/repo}" "spike" "FBCA04" "Throw-away exploration; exempt from AgDR + coverage gates"

# Pass the body via a file (arbitrary markdown — never inline-interpolated).
body_file="$(mktemp)"
cat > "$body_file" <<'BODY'
{formatted body}
BODY

# tracker_create <owner/repo> <title> <body_file> [<labels_csv>] → {"ref","url"}.
# It is gated by require-skill-for-issue-create.sh; the active-issue-skill marker
# written at skill entry keeps this call allowed.
result="$(tracker_create "{owner/repo}" "[Spike] {title}" "$body_file" "spike")"
rc=$?
rm -f "$body_file"
if [ "$rc" -eq 3 ]; then
  # tracker.kind=none (shape-only): no tracker to create in. tracker_create
  # printed the rendered ticket body to stdout — surface it for manual /
  # external filing instead of a non-existent CLI/auth failure.
  echo "Tracker is 'none' (shape-only) — nothing was created in a tracker." >&2
  echo "File this in your external system (e.g. Jira/Linear via MCP):" >&2
  printf '%s\n' "$result"
  exit 0
elif [ "$rc" -ne 0 ] || [ -z "$result" ]; then
  echo "Spike creation failed — check the tracker CLI / auth. Nothing was created." >&2
  exit 1
fi

ref="$(printf '%s' "$result" | jq -r '.ref')"
url="$(printf '%s' "$result" | jq -r '.url')"

The spike label is the trigger that downstream hooks (AgDR-required hooks, coverage gates) read to apply the workflow exemptions.

8. Return the URL + branch suggestion

Use the ref / url parsed from tracker_create in step 7:

Created: {owner/repo}#${ref} — {title}
${url}

When you start work:
  /start-ticket {owner/repo}#${ref}
  git checkout -b spike/GH-${ref}-{slug}

9. Remind the operator about the disposition gate

When the spike closes, run /spike-close to record the disposition:
  /spike-close --promote   # hypothesis confirmed → file a [Feature]
  /spike-close --discard   # hypothesis rejected → write a memo

Closing the spike without running this gate is allowed (closure is the
operator's call) but skips the memo / promotion artefact and leaves no
record of what was learned.

Rules

1. One question at a time. Never batch questions. Wait for each answer.
2. Always confirm before creating. Show the full ticket and get explicit "yes".
3. All four required fields are mandatory. Hypothesis, Budget, Kill Criteria, Disposition — none can be skipped or deferred.
4. Disposition is PROMOTE or DISCARD only. "Decide later" is not allowed; reject it and re-ask.
5. Labels. spike always. Priority labels (P0/P1/etc.) are NOT applied — spikes are time-boxed by Budget, not prioritised by P-class. The accepted prefix list reads from .claude/project-config.*.json → .ticket.prefix_whitelist; [Spike] must be in that list.
6. Branch suggestion. Always spike/<TICKET-ID>-<slug>. The branch name is what AgDR-exemption hooks check (alongside the active-ticket marker).
7. No PRD, no tech design. Spikes describe a hypothesis, not a feature. Don't ask for user stories, ACs, or design notes — those belong on the follow-up [Feature] ticket if the disposition is PROMOTE.

Workflow exemptions for spike work

A spike PR is exempt from the production SDLC subset listed below; everything else still applies. The exemptions are mechanical (hooks detect [Spike] prefix or spike label and skip), not advisory.

Gate	Production work	Spike work
Pre-Build (parent epic, story tickets, ACs, design review)	Required	Skipped — the spike ticket IS the unit
AgDR for technical decisions (require-agdr-for-arch-pr.sh, require-agdr-for-arch-changes.sh)	Required	Skipped — ship a memo on /spike-close --discard instead
Test coverage > 80%	Required	Skipped — coverage is irrelevant for throw-away code
Code Reviewer agent (Rex)	Required on every PR	Required — even throw-away code gets a sanity check
Security Auditor (auth/crypto/secrets diff)	Required	Required — security gates fire regardless of intent
Glossary in PR body	Required	Required — spike PRs explain WHAT WAS LEARNED, which is the artefact
QA Engineer verification	Required (AC verification)	Required (Hypothesis verification: did we answer the question?)
Disposition decision before close	N/A	Required — operator must declare PROMOTE or DISCARD via /spike-close

See .claude/rules/workflow-gates.md § Spike work for the rule statement, and AgDR-NNNN-spike-skill-schema-and-exemptions.md for the rationale.

---

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.