wtf.spike（哇哦 尖峰）

Spike

Run a time-boxed technical investigation. Core value: turns an unknown into a decision — produces concrete findings and a recommendation so the team can write specs confidently rather than guessing.

Process

0. GitHub CLI setup

Run steps 1–2 of ../references/gh-setup.md (install check and auth check). Stop if gh is not installed or not authenticated. Extensions are not required for this skill.

Skip this step if gh-setup was already confirmed this session.

1. Define the question

If the user described the investigation in their request, extract the core question from it. Otherwise call AskUserQuestion with:

• question: "What question should this spike answer?"
• header: "Spike question"
• options: pre-filled with 1–2 specific questions inferred from any context provided (e.g. linked Epic, conversation)

The question must be specific and answerable — not "how does caching work?" but "is Redis or in-memory caching the right choice for our session store given our deployment constraints?" — and scoped to a decision the team actually needs to make.

Then call AskUserQuestion with:

• question: "How much time should this spike take?"
• header: "Time box"
• options: [{label: "1 hour", description: "Quick feasibility check"}, {label: "Half day", description: "Moderate investigation"}, {label: "1 day", description: "Deep dive with proof of concept"}]

2. Identify the linked issue (optional)

Call AskUserQuestion with question: "Is this spike linked to an existing issue?", header: "Linked issue", and options pre-filled with recent open Epics and Features from gh issue list --label "epic,feature" --state open --limit 5, plus {label: "No linked issue", description: "Standalone investigation"}.

If linked: fetch the issue to extract domain context, constraints, and success metrics that inform the investigation scope.

3. Research

Run all research in parallel using the Agent tool:

Codebase exploration:

• Search for existing implementations, prior attempts, or ADRs addressing the same question (domain nouns, patterns, imports)
• Check docs/steering/TECH.md for constraints that rule out certain approaches
• Identify integration points and dependencies the solution must respect

External research (if available):

• Use WebSearch/WebFetch for relevant documentation, benchmarks, or known trade-offs

Synthesise findings internally. Do not dump raw research at the user.

4. Derive 2–3 concrete approaches

For each approach:

• Name: short label (e.g. "Redis session store", "In-memory with TTL")
• Summary: one sentence describing what it involves
• Pros: 2–3 concrete advantages relevant to this codebase and constraints
• Cons: 2–3 concrete risks or costs
• Effort estimate: rough implementation cost (hours or days)
• Fit with TECH.md: does it align with the established stack and patterns?

5. Recommend

State a single recommendation:

"Recommend [Approach N] because [1–2 key reasons]. Main risk: [X], mitigated by [Y]."

If evidence is genuinely ambiguous or the spike revealed the question is harder than expected, say so clearly — recommend a proof of concept or a follow-up spike with a narrower question.

6. Review with user

Show the full analysis (approaches + recommendation). Then call AskUserQuestion with:

• question: "Does this answer the question well enough to proceed?"
• header: "Spike review"
• options: [{label: "Yes — record the findings", description: "Write the spike doc"}, {label: "Need more depth on one approach", description: "Explore a specific area further"}, {label: "Question changed", description: "The investigation revealed a different question"}]

Apply any adjustments, then proceed.

7. Write the findings doc

Write to docs/spikes/<YYYY-MM-DD>-<slug>.md where <slug> is a 2–4 word kebab-case summary of the question (e.g. session-store-strategy).

Structure:

# Spike: <question>

**Date:** <YYYY-MM-DD>
**Time box:** <duration>
**Linked issue:** #<n> or —

## Question

<the specific question this spike answered>

## Approaches considered

### <Approach 1 name>
**Summary:** ...
**Pros:** ...
**Cons:** ...
**Effort:** ...

### <Approach 2 name>
...

## Recommendation

<recommendation text>

## Decision

<!-- Fill when the team decides -->
- [ ] Accepted — proceeding with [approach]
- [ ] Rejected — reason: ...
- [ ] Needs follow-up: ...

mkdir -p docs/spikes
git add docs/spikes/<filename>
git commit -m "docs(spike): <question summary>"

Print the file path.

8. Post to linked issue (if applicable)

If a linked issue exists, post a comment:

gh issue comment <issue_number> --body "🔬 Spike concluded: **<question>** → Recommendation: <one-line summary>. Full findings: docs/spikes/<filename>.md"

9. Offer next steps

Call AskUserQuestion with:

• question: "What's next?"
• header: "Next step"
• options: [{label: "Write an Epic from this", description: "Turn the recommendation into an Epic issue (default)"}, {label: "Write a Task from this", description: "The spike uncovered a specific narrow change"}, {label: "Stop here", description: "Exit — the team will decide separately"}]
• Write an Epic → follow the wtf.write-epic process, seeding it with the spike's recommendation and findings as context.
• Write a Task → follow the wtf.write-task process with the spike recommendation as the task description.
• Stop here → exit.