me2resh/apexyard / .claude/skills/spike-close
spike-close
VerifiedClose a spike via the disposition gate — `--promote` files a [Feature] follow-up, `--discard` writes a memo.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.0 KB |
SKILL.md
View on GitHub---
name: spike-close
description: Close a spike via the disposition gate — `--promote` files a [Feature] follow-up, `--discard` writes a memo.
argument-hint: "--promote | --discard [<spike-ticket-number>]"
allowed-tools: Bash, Read, Write
---
Writing: read docs/skills/shared/writing-rule.md before you write a durable artifact.
# /spike-close — Close a Spike via the Disposition Gate
The disposition gate prevents the worst-of-both case: a spike that "succeeded" but never decides what to do with the code, leaving half-shipped exploration in main. Every spike must close with one of two paths:
- **PROMOTE** — the hypothesis was confirmed; file a fresh `[Feature]` ticket so the work goes through the full production SDLC. The spike branch itself is NOT lifted into production — the new feature work re-implements based on the spike's findings.
- **DISCARD** — the hypothesis was rejected (or the answer is "we shouldn't do this"); delete the spike branch and write a memo at `docs/spike-memos/<slug>.md` so future-us doesn't re-explore the same ground.
## 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:
```bash
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. See `docs/multi-project.md`.
## Usage
```
/spike-close --promote 142
/spike-close --discard 142
/spike-close --promote # uses the active-ticket marker
/spike-close --discard
```
## Process
### 1. Resolve the spike ticket
Two paths:
- If `$ARGUMENTS` includes a number (e.g. `--promote 142` or `--discard owner/repo#142`), use that.
- Otherwise read the active-ticket marker of the working tree you are in (see `/start-ticket` "Read the active ticket") and use the ticket recorded there. If no marker resolves, ask:
```
Which spike are you closing? Pass --promote <number> or --discard <number>,
or run /start-ticket first.
```
### 2. Verify it really is a spike
Run `gh issue view <number> --repo <owner/repo> --json title,labels,state,body`. The skill proceeds if:
- title starts with `[Spike]`, OR
- labels include `spike`
If the ticket is neither, refuse:
```
Issue {owner/repo}#{number} doesn't look like a spike (no [Spike] prefix,
no `spike` label). /spike-close is for spike disposition only — close
production-shaped tickets via the normal QA → Done flow.
```
If the ticket is already CLOSED, warn and ask whether to continue (the user may want to retroactively record disposition):
```
{owner/repo}#{number} is already closed. Continue and (a) file the follow-
up artefact only, or (b) abort? (continue / abort)
```
### 3. Branch on `--promote` vs `--discard`
#### 3a. PROMOTE — three questions, then file a [Feature]
Ask one at a time:
**i) Production-shaped feature title**
```
The spike confirmed the hypothesis. What's the title of the production-
shaped feature ticket we're filing as the follow-up?
```
**ii) Production-shaped scope**
```
What's the scope for the production version? This is the user-facing
capability, not the spike's exploration goal.
(One paragraph or bullets.)
```
**iii) What's NOT being carried over**
```
What did the spike try that's NOT being lifted into production? (e.g.
"the prototype used in-memory storage; production needs Postgres",
"the spike skipped error handling — we'll add it in the feature".)
```
Then preview the [Feature] ticket and confirm. The body MUST include a
"Spike findings" section that links back to the spike:
```
**[Feature] {title}**
## User Story
{prompted from the operator — same as /feature step 3a}
## Acceptance Criteria
- [ ] {prompted from the operator}
## Spike findings
This feature was promoted from {owner/repo}#{spike-number}.
The spike confirmed: {one-sentence summary of what the spike proved}.
What is NOT being carried over from the spike branch:
- {item 1}
- {item 2}
## Out of Scope
{or "—"}
```
After confirmation, create the follow-up feature via the tracker abstraction
(`tracker_create`, #670 / AgDR-0072, extended by the #709 creator sweep) so it
lands in **this project's** tracker. For a GitHub adopter this runs
`gh issue create` exactly as before.
```bash
# 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"
body_file="$(mktemp)"
cat > "$body_file" <<'BODY'
{body}
BODY
# tracker_create <owner/repo> <title> <body_file> [<labels_csv>] → {"ref","url"}.
result="$(tracker_create "{owner/repo}" "[Feature] {title}" "$body_file" "enhancement")"
rc=$?
rm -f "$body_file"
if [ "$rc" -eq 3 ]; then
echo "Tracker is 'none' (shape-only) — nothing was created in a tracker." >&2
printf '%s\n' "$result"
exit 0
elif [ "$rc" -ne 0 ] || [ -z "$result" ]; then
echo "Follow-up creation failed — check the tracker CLI / auth. Nothing was created." >&2
exit 1
fi
ref="$(printf '%s' "$result" | jq -r '.ref')" # the new feature's reference
url="$(printf '%s' "$result" | jq -r '.url')"
```
Then close the spike with a cross-ref comment. (Closing stays on `gh` here —
issue *state transitions* are out of scope for the #709 creation sweep; a
tracker-agnostic close/state primitive is separate follow-up work. On a
non-GitHub project, close the spike manually.)
```bash
gh issue close {spike-number} --repo {owner/repo} \
--comment "Spike disposition: PROMOTE. Follow-up filed as #${ref} — {feature-title}. Spike branch is NOT being lifted into production; the new feature work re-implements based on the findings recorded above."
```
Return both URLs:
```
Spike closed: {owner/repo}#{spike-number}
Follow-up: {owner/repo}#${ref} — {feature-title}
${url}
```
#### 3b. DISCARD — one question, then write a memo
```
What did we learn? One paragraph — enough that a future engineer who
asks the same question (or revisits the same library / approach) finds
this memo and doesn't re-explore the same ground. Be concrete:
- what was the hypothesis?
- what did the experiment show?
- why is the answer no? (or "we shouldn't do this", or "X first")
- what would change the answer? (under what conditions might we revisit?)
```
Then derive a slug from the spike title (lowercase, kebab-case, max 40 chars,
stopwords trimmed) and write the memo:
```bash
mkdir -p docs/spike-memos
cat > docs/spike-memos/{slug}.md <<'EOF'
# Spike memo: {title}
> **Disposition: DISCARD** — hypothesis rejected; not pursuing further.
- **Spike ticket**: {owner/repo}#{number}
- **Author**: {git config user.name}
- **Closed**: {ISO-8601 date}
## Hypothesis (from the spike ticket)
{hypothesis from the original ticket body}
## Findings
{the one-paragraph answer the operator wrote}
## Why we're not pursuing
{extracted from the operator's answer — the "answer is no" part}
## What would change the answer
{conditions under which we might revisit — extracted from the operator's
answer, or "—" if not specified}
## Artefacts
- Original spike ticket: {owner/repo}#{number}
- Spike branch: spike/<TICKET-ID>-<slug> (delete after merge of this memo)
EOF
```
The memo is committed in a separate PR (the spike's PR may or may not have merged — the memo PR is the disposition artefact, separate from any code).
After writing the memo, close the spike with a cross-ref:
```bash
gh issue close {spike-number} --repo {owner/repo} \
--comment "Spike disposition: DISCARD. Memo at docs/spike-memos/{slug}.md (commit in follow-up PR). Spike branch can be deleted; nothing is being lifted into production."
```
Return:
```
Spike closed: {owner/repo}#{spike-number}
Memo path: docs/spike-memos/{slug}.md
Next steps:
1. Stage the memo: git add docs/spike-memos/{slug}.md
2. Commit: git commit -m "docs: spike memo for #{spike-number}"
3. Push + PR — the memo is the disposition artefact.
4. Delete the spike branch once the memo PR merges.
```
## Rules
1. **Disposition is PROMOTE or DISCARD only.** No third path. The whole point of the gate is to forbid "decide later".
2. **PROMOTE files a fresh [Feature].** The spike branch is NOT lifted into production. Promotion creates a new ticket; the production work re-implements based on the findings.
3. **DISCARD writes a memo.** Spike-memo at `docs/spike-memos/<slug>.md` is the artefact — no memo, no DISCARD.
4. **One question at a time.** Same conversational rule as `/spike` and `/feature`.
5. **No hard block on closing without /spike-close.** The skill prompts; closure is ultimately the operator's call. The cost of forgetting is no record of what was learned, which is enough downside to motivate running the gate without needing a mechanical block.
6. **Cross-references both ways.** PROMOTE links the new feature back to the spike; DISCARD links the memo back to the spike. Future archaeology should always find the trail.
## Edge cases
- **Spike PR didn't merge.** Fine — the memo / follow-up feature is the disposition artefact, not the spike code itself. PROMOTE: file the new feature, close the spike, abandon the branch. DISCARD: write the memo, close the spike, abandon the branch.
- **Spike's hypothesis was partially confirmed.** Treat the partial confirmation as PROMOTE — file the [Feature] for the part that worked; cover the part that didn't in the "What is NOT being carried over" section. Don't try to split the disposition.
- **Multiple spikes feeding one feature.** PROMOTE each spike individually with the same target [Feature] title; the feature ticket's body lists all promoting spikes in the "Spike findings" section.
---
*Part of [ApexYard](https://github.com/me2resh/apexyard) — multi-project SDLC framework for Claude Code · MIT.*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |