golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix: sync spike/sketch workflows with upstream skill v2 improvements

Browse Source 
Spike workflow:
- Add frontier mode (no-arg or "frontier" proposes integration + frontier spikes)
- Add depth-over-speed principle — follow surprising findings, test edge cases,
  document investigation trail not just verdict
- Add CONVENTIONS.md awareness — follow established patterns, update after session
- Add Requirements section in MANIFEST — track design decisions as they emerge
- Add re-ground step before each spike to prevent drift in long sessions
- Add Investigation Trail section to README template
- Restructured prior context loading with priority ordering
- Research step now runs per-spike with briefing and approach comparison table

Sketch workflow:
- Add frontier mode (no-arg or "frontier" proposes consistency + frontier sketches)
- Add spike context loading — ground mockups in real data shapes, requirements,
  and conventions from spike findings

Spike wrap-up workflow:
- Add CONVENTIONS.md generation step (recurring stack/structure/pattern choices)
- Reference files now use implementation blueprint format (Requirements, How to
  Build It, What to Avoid, Constraints)
- SKILL.md now includes requirements section from MANIFEST
- Next-steps route to /gsd-spike frontier mode instead of inline analysis

Sketch wrap-up workflow:
- Next-steps route to /gsd-sketch frontier mode

Commands updated with frontier mode in descriptions and argument hints.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-04-21 09:05:11 -06:00
parent 2980f0ec48
commit 969ee38ee5
6 changed files with 422 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
commands/gsd/sketch.md
View File

@@ -1,7 +1,7 @@
---
name: gsd:sketch
description: Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration
argument-hint: "<design idea to explore> [--quick] [--text]"
description: Sketch UI/design ideas with throwaway HTML mockups, or propose what to sketch next (frontier mode)
argument-hint: "[design idea to explore] [--quick] [--text] or [frontier]"
allowed-tools:
- Read
- Write
@@ -18,7 +18,12 @@ allowed-tools:
<objective>
Explore design directions through throwaway HTML mockups before committing to implementation.
Each sketch produces 2-3 variants for comparison. Sketches live in `.planning/sketches/` and
integrate with GSD commit patterns, state tracking, and handoff workflows.
integrate with GSD commit patterns, state tracking, and handoff workflows. Loads spike
findings to ground mockups in real data shapes and validated interaction patterns.
Two modes:
- **Idea mode** (default) — describe a design idea to sketch
- **Frontier mode** (no argument or "frontier") — analyzes existing sketch landscape and proposes consistency and frontier sketches
Does not require `/gsd-new-project` — auto-creates `.planning/sketches/` if needed.
</objective>

15
commands/gsd/spike.md
View File

@@ -1,7 +1,7 @@
---
name: gsd:spike
description: Rapidly spike an idea with throwaway experiments to validate feasibility before planning
argument-hint: "<idea to validate> [--quick] [--text]"
description: Spike an idea through experiential exploration, or propose what to spike next (frontier mode)
argument-hint: "[idea to validate] [--quick] [--text] or [frontier]"
allowed-tools:
- Read
- Write
@@ -16,9 +16,14 @@ allowed-tools:
- mcp__context7__query-docs
---
<objective>
Rapid feasibility validation through focused, throwaway experiments. Each spike answers one
specific question with observable evidence. Spikes live in `.planning/spikes/` and integrate
with GSD commit patterns, state tracking, and handoff workflows.
Spike an idea through experiential exploration — build focused experiments to feel the pieces
of a future app, validate feasibility, and produce verified knowledge for the real build.
Spikes live in `.planning/spikes/` and integrate with GSD commit patterns, state tracking,
and handoff workflows.
Two modes:
- **Idea mode** (default) — describe an idea to spike
- **Frontier mode** (no argument or "frontier") — analyzes existing spike landscape and proposes integration and frontier spikes
Does not require `/gsd-new-project` — auto-creates `.planning/spikes/` if needed.
</objective>

10
get-shit-done/workflows/sketch-wrap-up.md
View File

@@ -255,15 +255,16 @@ The sketch-findings skill will auto-load when building the UI.
## ▶ Next Up
**Start building** — implement the validated design
**Explore frontier sketches** — see what else is worth sketching based on what we've explored
`/gsd-plan-phase`
`/gsd-sketch` (run with no argument — its frontier mode analyzes the sketch landscape and proposes consistency and frontier sketches)
───────────────────────────────────────────────────────────────
**Also available:**
- `/gsd-plan-phase` — start building the real UI
- `/gsd-ui-phase` — generate a UI design contract for a frontend phase
- `/gsd-sketch` — sketch additional design areas
- `/gsd-sketch [idea]` — sketch a specific new design area
- `/gsd-explore` — continue exploring
───────────────────────────────────────────────────────────────
@@ -279,5 +280,6 @@ The sketch-findings skill will auto-load when building the UI.
- [ ] Reference files contain design decisions, CSS patterns, HTML structures, anti-patterns
- [ ] `.planning/sketches/WRAP-UP-SUMMARY.md` written for project history
- [ ] Project CLAUDE.md has auto-load routing line
- [ ] Summary presented with next-step routing
- [ ] Summary presented
- [ ] Next-step options presented (including frontier sketch exploration via `/gsd-sketch`)
</success_criteria>

136
get-shit-done/workflows/sketch.md
View File

@@ -2,6 +2,10 @@
Explore design directions through throwaway HTML mockups before committing to implementation.
Each sketch produces 2-3 variants for comparison. Saves artifacts to `.planning/sketches/`.
Companion to `/gsd-sketch-wrap-up`.
Supports two modes:
- **Idea mode** (default) — user describes a design idea to sketch
- **Frontier mode** — no argument or "frontier" / "what should I sketch?" — analyzes existing sketch landscape and proposes consistency and frontier sketches
</purpose>
<required_reading>
@@ -25,9 +29,60 @@ Read all files referenced by the invoking prompt's execution_context before star
Parse `$ARGUMENTS` for:
- `--quick` flag → set `QUICK_MODE=true`
- `--text` flag → set `TEXT_MODE=true`
- `frontier` or empty → set `FRONTIER_MODE=true`
- Remaining text → the design idea to sketch
**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
**Text mode:** If TEXT_MODE is enabled, replace AskUserQuestion calls with plain-text numbered lists.
</step>
<step name="route">
## Routing
- **FRONTIER_MODE is true** → Jump to `frontier_mode`
- **Otherwise** → Continue to `setup_directory`
</step>
<step name="frontier_mode">
## Frontier Mode — Propose What to Sketch Next
### Load the Sketch Landscape
If no `.planning/sketches/` directory exists, tell the user there's nothing to analyze and offer to start fresh with an idea instead.
Otherwise, load in this order:
**a. MANIFEST.md** — the design direction, reference points, and sketch table with winners.
**b. Findings skills** — glob `./.claude/skills/sketch-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain curated design decisions from prior wrap-ups.
**c. All sketch READMEs** — read `.planning/sketches/*/README.md` for design questions, winners, and tags.
### Analyze for Consistency Sketches
Review winning variants across all sketches. Look for:
- **Visual consistency gaps:** Two sketches made independent design choices that haven't been tested together.
- **State combinations:** Individual states validated but not seen in sequence.
- **Responsive gaps:** Validated at one viewport but the real app needs multiple.
- **Theme coherence:** Individual components look good but haven't been composed into a full-page view.
If consistency risks exist, present them as concrete proposed sketches with names and design questions. If no meaningful gaps, say so and skip.
### Analyze for Frontier Sketches
Think laterally about the design direction from MANIFEST.md and what's been explored:
- **Unsketched screens:** UI surfaces assumed but unexplored.
- **Interaction patterns:** Static layouts validated but transitions, loading, drag-and-drop need feeling.
- **Edge case UI:** 0 items, 1000 items, errors, slow connections.
- **Alternative directions:** Fresh takes on "fine but not great" sketches.
- **Polish passes:** Typography, spacing, micro-interactions, empty states.
Present frontier sketches as concrete proposals numbered from the highest existing sketch number.
### Get Alignment and Execute
Present all consistency and frontier candidates, then ask which to run. When the user picks sketches, update `.planning/sketches/MANIFEST.md` and proceed directly to building them starting at `build_sketches`.
</step>
<step name="setup_directory">
@@ -49,25 +104,45 @@ COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true")
</step>
<step name="mood_intake">
**If `QUICK_MODE` is true:** Skip mood intake. Use whatever the user provided in `$ARGUMENTS` as the design direction. Jump to `decompose`.
**If `QUICK_MODE` is true:** Skip mood intake. Use whatever the user provided in `$ARGUMENTS` as the design direction. Jump to `load_spike_context`.
**Otherwise:**
Before sketching anything, explore the design intent through conversation. Ask one question at a time using AskUserQuestion, with a paragraph of context and reasoning for each.
Before sketching anything, explore the design intent through conversation. Ask one question at a time — using AskUserQuestion in normal mode, or a plain-text numbered list if TEXT_MODE is active.
**Questions to cover (adapt to what the user has already shared):**
1. **Feel:** "What should this feel like? Give me adjectives, emotions, or a vibe." (e.g., "clean and clinical", "warm and playful", "dense and powerful")
2. **References:** "What apps, sites, or products have a similar feel to what you're imagining?" (gives concrete visual anchors)
3. **Core action:** "What's the single most important thing a user does here?" (focuses the sketch on what matters)
1. **Feel:** "What should this feel like? Give me adjectives, emotions, or a vibe."
2. **References:** "What apps, sites, or products have a similar feel to what you're imagining?"
3. **Core action:** "What's the single most important thing a user does here?"
You may need more or fewer questions depending on how much the user shares upfront. After each answer, briefly reflect what you heard and how it shapes your thinking.
After each answer, briefly reflect what you heard and how it shapes your thinking.
When you have enough signal, ask: **"I think I have a good sense of the direction. Ready for me to sketch, or want to keep discussing?"**
Only proceed when the user says go.
</step>
<step name="load_spike_context">
## Load Spike Context
If spikes exist for this project, read them to ground the sketches in reality. Mockups are still pure HTML, but they should reflect what's actually been proven — real data shapes, real component names, real interaction patterns.
**a.** Glob for `./.claude/skills/spike-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain validated patterns and requirements.
**b.** Read `.planning/spikes/MANIFEST.md` if it exists — check the Requirements section for non-negotiable design constraints (e.g., "must support streaming", "must render markdown"). These requirements should be visible in the mockup even though the mockup doesn't implement them for real.
**c.** Read `.planning/spikes/CONVENTIONS.md` if it exists — the established stack informs what's buildable and what interaction patterns are idiomatic.
**How spike context improves sketches:**
- Use real field names and data shapes from spike findings instead of generic placeholders
- Show realistic UI states that match what the spikes proved (e.g., if streaming was validated, show a streaming message state)
- Reference real component names and patterns from the target stack
- Include interaction states that reflect what the spikes discovered (loading, error, reconnection states)
**If no spikes exist**, skip this step.
</step>
<step name="decompose">
Break the idea into 2-5 design questions. Present as a table:
@@ -98,18 +173,18 @@ Before sketching, ground the design in what's actually buildable. Sketches are H
**a. Identify the target stack.** Check for package.json, Cargo.toml, etc. If the user mentioned a framework (React, SwiftUI, Flutter, etc.), note it.
**b. Check component/pattern availability.** Use context7 (resolve-library-id → query-docs) or web search to answer:
- What layout primitives does the target framework provide? (grid systems, nav patterns, panel components)
- Are there existing component libraries in use? (shadcn, Material UI, etc.) What components are available?
- What interaction patterns are idiomatic? (e.g., sheet vs modal vs dialog in mobile)
- What layout primitives does the target framework provide?
- Are there existing component libraries in use? What components are available?
- What interaction patterns are idiomatic?
**c. Note constraints that affect design.** Some things that look great in HTML are painful or impossible in certain stacks:
**c. Note constraints that affect design:**
- Platform conventions (iOS nav patterns, desktop menu bars, terminal grid constraints)
- Framework limitations (what's easy vs requires custom work)
- Existing design tokens or theme systems already in the project
**d. Let research inform variants.** Use findings to make variants that are actually buildable — at least one variant should follow the path of least resistance for the target stack.
**d. Let research inform variants.** At least one variant should follow the path of least resistance for the target stack.
**Skip when unnecessary.** If it's a greenfield project with no stack chosen, or the user explicitly says "just explore visually, don't worry about implementation," skip this step entirely. The point is grounding, not gatekeeping.
**Skip when unnecessary.** Greenfield project with no stack, or user says "just explore visually." The point is grounding, not gatekeeping.
</step>
<step name="create_manifest">
@@ -144,26 +219,24 @@ Build each sketch in order.
### For Each Sketch:
**a.** Find next available number by checking existing `.planning/sketches/NNN-*/` directories.
Format: three-digit zero-padded + hyphenated descriptive name.
**a.** Find next available number. Format: three-digit zero-padded + hyphenated descriptive name.
**b.** Create the sketch directory: `.planning/sketches/NNN-descriptive-name/`
**c.** Build `index.html` with 2-3 variants:
**First round — dramatic differences:** Build 2-3 meaningfully different approaches to the design question. Different layouts, different visual structures, different interaction models.
**Subsequent rounds — refinements:** Once the user has picked a direction or cherry-picked elements, build subtler variations within that direction.
**First round — dramatic differences:** 2-3 meaningfully different approaches.
**Subsequent rounds — refinements:** Subtler variations within the chosen direction.
Each variant is a page/tab in the same HTML file. Include:
- Tab navigation to switch between variants (see `sketch-variant-patterns.md`)
- Clear labels: "Variant A: Sidebar Layout", "Variant B: Top Nav", etc.
- The sketch toolbar (see `sketch-tooling.md`)
- All interactive elements functional (see `sketch-interactivity.md`)
- Real-ish content, not lorem ipsum
- Real-ish content, not lorem ipsum (use real field names from spike context if available)
- Link to `../themes/default.css` for shared theme variables
**All sketches are plain HTML with inline CSS and JS.** No build step, no npm, no framework. Opens instantly in a browser.
**All sketches are plain HTML with inline CSS and JS.** No build step, no npm, no framework.
**d.** Write `README.md`:
@@ -210,16 +283,16 @@ Compare: {what to look for between variants}
──────────────────────────────────────────────────────────────
**f.** Handle feedback:
- **Pick a direction:** "I like variant B" → mark winner in README, move to next sketch
- **Cherry-pick elements:** "Rounded edges from A, color treatment from C" → build a synthesis as a new variant, show again
- **Want more exploration:** "None of these feel right, try X instead" → build new variants
- **Pick a direction:** mark winner, move to next sketch
- **Cherry-pick elements:** build synthesis as new variant, show again
- **Want more exploration:** build new variants
Iterate until the user is satisfied with a direction for this sketch.
Iterate until satisfied.
**g.** Finalize:
1. Mark the winning variant in the README frontmatter (`winner: "B"`)
2. Add ★ indicator to the winning tab in the HTML
3. Update `.planning/sketches/MANIFEST.md` with the sketch row
1. Mark winning variant in README frontmatter (`winner: "B"`)
2. Add ★ indicator to winning tab in HTML
3. Update `.planning/sketches/MANIFEST.md`
**h.** Commit (if `COMMIT_DOCS` is true):
```bash
@@ -235,7 +308,7 @@ gsd-sdk query commit "docs(sketch-NNN): [winning direction] — [key visual insi
</step>
<step name="report">
After all sketches complete, present the summary:
After all sketches complete:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -263,8 +336,8 @@ After all sketches complete, present the summary:
───────────────────────────────────────────────────────────────
**Also available:**
- `/gsd-sketch` — sketch more (or run with no argument for frontier mode)
- `/gsd-plan-phase` — start building the real UI
- `/gsd-explore` — continue exploring the concept
- `/gsd-spike` — spike technical feasibility of a design pattern
───────────────────────────────────────────────────────────────
@@ -275,8 +348,9 @@ After all sketches complete, present the summary:
<success_criteria>
- [ ] `.planning/sketches/` created (auto-creates if needed, no project init required)
- [ ] Design direction explored conversationally before any code (unless --quick)
- [ ] Target stack researched — component availability, constraints, and idioms noted (unless greenfield/skipped)
- [ ] Each sketch has 2-3 variants for comparison (at least one follows path of least resistance for target stack)
- [ ] Spike context loaded — real data shapes, requirements, and conventions inform mockups
- [ ] Target stack researched — component availability, constraints, idioms (unless greenfield/skipped)
- [ ] Each sketch has 2-3 variants for comparison (at least one follows path of least resistance)
- [ ] User can open and interact with sketches in a browser
- [ ] Winning variant selected and marked for each sketch
- [ ] All variants preserved (winner marked, not others deleted)

139
get-shit-done/workflows/spike-wrap-up.md
View File

@@ -1,8 +1,8 @@
<purpose>
Curate spike experiment findings and package them into a persistent project skill for future
build conversations. Reads from `.planning/spikes/`, writes skill to `./.claude/skills/spike-findings-[project]/`
(project-local) and summary to `.planning/spikes/WRAP-UP-SUMMARY.md`.
Companion to `/gsd-spike`.
Package spike experiment findings into a persistent project skill — an implementation blueprint
for future build conversations. Reads from `.planning/spikes/`, writes skill to
`./.claude/skills/spike-findings-[project]/` (project-local) and summary to
`.planning/spikes/WRAP-UP-SUMMARY.md`. Companion to `/gsd-spike`.
</purpose>
<required_reading>
@@ -22,7 +22,7 @@ Read all files referenced by the invoking prompt's execution_context before star
<step name="gather">
## Gather Spike Inventory
1. Read `.planning/spikes/MANIFEST.md` for the overall idea context
1. Read `.planning/spikes/MANIFEST.md` for the overall idea context and requirements
2. Glob `.planning/spikes/*/README.md` and parse YAML frontmatter from each
3. Check if `./.claude/skills/spike-findings-*/SKILL.md` exists for this project
- If yes: read its `processed_spikes` list from the metadata section and filter those out
@@ -93,21 +93,29 @@ For each included spike:
<step name="synthesize">
## Synthesize Reference Files
For each feature-area group, write a reference file at `references/[feature-area-name].md`:
For each feature-area group, write a reference file at `references/[feature-area-name].md` as an **implementation blueprint** — it should read like a recipe, not a research paper. A future build session should be able to follow this and build the feature correctly without re-spiking anything.
```markdown
# [Feature Area Name]
## Validated Patterns
[For each validated finding: describe the approach that works, include key code snippets extracted from the spike source, explain why it works]
## Requirements
## Landmines
[Things that look right but aren't. Gotchas. Anti-patterns discovered during spiking.]
[Non-negotiable design decisions from MANIFEST.md Requirements section that apply to this feature area. These MUST be honored in the real build. E.g., "Must use streaming JSON output", "Must support reconnection".]
## How to Build It
[Step-by-step: what to install, how to configure, what code pattern to use. Include key code snippets extracted from the spike source. This is the proven approach — not theory, but tested and working code.]
## What to Avoid
[Things that look right but aren't. Gotchas. Anti-patterns discovered during spiking. Dead ends that were tried and failed.]
## Constraints
[Hard facts: rate limits, library limitations, version requirements, incompatibilities]
## Origin
Synthesized from spikes: NNN, NNN, NNN
Source files available in: sources/NNN-spike-name/, sources/NNN-spike-name/
```
@@ -121,7 +129,7 @@ Create (or update) the generated skill's SKILL.md:
```markdown
---
name: spike-findings-[project-dir-name]
description: Validated patterns, constraints, and implementation knowledge from spike experiments. Auto-loaded during implementation work on [project-dir-name].
description: Implementation blueprint from spike experiments. Requirements, proven patterns, and verified knowledge for building [project-dir-name]. Auto-loaded during implementation work.
---
<context>
@@ -132,6 +140,15 @@ description: Validated patterns, constraints, and implementation knowledge from
Spike sessions wrapped: [date(s)]
</context>
<requirements>
## Requirements
[Copied directly from MANIFEST.md Requirements section. These are non-negotiable design decisions that emerged from the user's choices during spiking. Every feature area reference must honor these.]
- [requirement 1]
- [requirement 2]
</requirements>
<findings_index>
## Feature Areas
@@ -189,11 +206,47 @@ Add an auto-load routing line to the project's CLAUDE.md (create the file if it
If this routing line already exists (append mode), leave it as-is.
</step>
<step name="generate_conventions">
## Generate or Update CONVENTIONS.md
Analyze all processed spikes for recurring patterns and write `.planning/spikes/CONVENTIONS.md`. This file tells future spike sessions *how we spike* — the stack, structure, and patterns that have been established.
1. Read all spike source code and READMEs looking for:
- **Stack choices** — What language/framework/runtime appears across multiple spikes?
- **Structure patterns** — Common file layouts, port numbers, naming schemes
- **Recurring approaches** — How auth is handled, how styling is done, how data is served
- **Tools & libraries** — Packages that showed up repeatedly with versions that worked
2. Write or update `.planning/spikes/CONVENTIONS.md`:
```markdown
# Spike Conventions
Patterns and stack choices established across spike sessions. New spikes follow these unless the question requires otherwise.
## Stack
[What we use for frontend, backend, scripts, and why — derived from what repeated across spikes]
## Structure
[Common file layouts, port assignments, naming patterns]
## Patterns
[Recurring approaches: how we handle auth, how we style, how we serve, etc.]
## Tools & Libraries
[Preferred packages with versions that worked, and any to avoid]
```
3. Only include patterns that appeared in 2+ spikes or were explicitly chosen by the user.
4. If `CONVENTIONS.md` already exists (append mode), update sections with new patterns. Remove entries contradicted by newer spikes.
</step>
<step name="commit">
Commit all artifacts (if `COMMIT_DOCS` is true):
```bash
gsd-sdk query commit "docs(spike-wrap-up): package [N] spike findings into project skill" .planning/spikes/WRAP-UP-SUMMARY.md
gsd-sdk query commit "docs(spike-wrap-up): package [N] spike findings into project skill" .planning/spikes/WRAP-UP-SUMMARY.md .planning/spikes/CONVENTIONS.md
```
</step>
@@ -206,6 +259,7 @@ gsd-sdk query commit "docs(spike-wrap-up): package [N] spike findings into proje
**Processed:** {N} spikes
**Feature areas:** {list}
**Skill:** `./.claude/skills/spike-findings-[project]/`
**Conventions:** `.planning/spikes/CONVENTIONS.md`
**Summary:** `.planning/spikes/WRAP-UP-SUMMARY.md`
**CLAUDE.md:** routing line added
@@ -214,56 +268,27 @@ The spike-findings skill will auto-load in future build conversations.
</step>
<step name="whats_next">
## What's Next — Intelligent Spike Routing
## What's Next
Analyze the full spike landscape (MANIFEST.md, all curated findings, feature-area groupings, validated/invalidated/partial verdicts) and present three categories of next-step options:
After the summary, present next-step options:
### Category A: Integration Spikes — "Do any validated spikes need to be tested together?"
───────────────────────────────────────────────────────────────
Review every pair and cluster of VALIDATED spikes. Look for:
## ▶ Next Up
- **Shared resources:** Two spikes that both touch the same API, database, state, or data format but were tested independently. Will they conflict, race, or step on each other?
- **Data handoffs:** Spike A produces output that Spike B consumes. The formats were assumed compatible but never proven.
- **Timing/ordering:** Spikes that work in isolation but have sequencing dependencies in the real flow (e.g., auth must complete before streaming starts).
- **Resource contention:** Spikes that individually work but may compete for connections, memory, rate limits, or tokens when combined.
**Explore frontier spikes** — see what else is worth spiking based on what we've learned
If integration risks exist, present them as concrete proposed spikes:
`/gsd-spike` (run with no argument — its frontier mode analyzes the spike landscape and proposes integration and frontier spikes)
> **Integration spike candidates:**
> - "Spikes 001 + 003 together: streaming through the authenticated connection" — these were tested separately but the real app needs both at once
> - "Spikes 002 + 005 data handoff: does the parser output match what the renderer expects?"
───────────────────────────────────────────────────────────────
If no meaningful integration risks exist, say so and skip this category.
### Category B: Frontier Spikes — "What else should we spike?"
Think laterally about the overall idea from MANIFEST.md and what's been proven so far. Consider:
- **Gaps in the vision:** What does the user's idea need that hasn't been spiked yet? Look at the MANIFEST.md idea description and identify capabilities that are assumed but unproven.
- **Discovered dependencies:** Findings from completed spikes that reveal new questions. A spike that validated "X works" may imply "but we'd also need Y" — surface those implied needs.
- **Alternative approaches:** If any spike was PARTIAL or INVALIDATED, suggest a different angle to achieve the same goal.
- **Adjacent capabilities:** Things that aren't strictly required but would meaningfully improve the idea if feasible — worth a quick spike to find out.
- **Comparison opportunities:** If a spike used one library/approach and it worked but felt heavy or awkward, suggest a comparison spike with an alternative.
Present frontier spikes as concrete proposals with names, validation questions (Given/When/Then), and risk-ordering:
> **Frontier spike candidates:**
> 1. `NNN-descriptive-name` — Given [X], when [Y], then [Z]. *Why now: [reason this is the logical next thing to explore]*
> 2. `NNN-descriptive-name` — Given [X], when [Y], then [Z]. *Why now: [reason]*
Number them continuing from the highest existing spike number.
### Category C: Standard Options
- `/gsd-plan-phase` — Start planning the real implementation
- `/gsd-add-phase` — Add a phase based on spike findings
- `/gsd-spike` — Spike additional ideas
- `/gsd-explore` — Continue exploring
**Also available:**
- `/gsd-plan-phase` — start planning the real implementation
- `/gsd-spike [idea]` — spike a specific new idea
- `/gsd-explore` — continue exploring
- Other
### Presenting the Options
Present all applicable categories, then ask the user which direction to go. If the user picks a frontier or integration spike, write the spike definitions directly into `.planning/spikes/MANIFEST.md` (appending to the existing table) and kick off `/gsd-spike` with those spikes pre-defined — the user shouldn't have to re-describe what was just proposed.
───────────────────────────────────────────────────────────────
</step>
</process>
@@ -271,11 +296,11 @@ Present all applicable categories, then ask the user which direction to go. If t
<success_criteria>
- [ ] All unprocessed spikes auto-included and processed
- [ ] Spikes grouped by feature area
- [ ] Spike-findings skill exists at `./.claude/skills/` with SKILL.md, references/, sources/
- [ ] Core source files from all spikes copied into sources/
- [ ] Reference files contain validated patterns, code snippets, landmines, constraints
- [ ] Spike-findings skill exists at `./.claude/skills/` with SKILL.md (including requirements), references/, sources/
- [ ] Reference files are implementation blueprints with Requirements, How to Build It, What to Avoid, Constraints
- [ ] `.planning/spikes/CONVENTIONS.md` created or updated with recurring stack/structure/pattern choices
- [ ] `.planning/spikes/WRAP-UP-SUMMARY.md` written for project history
- [ ] Project CLAUDE.md has auto-load routing line
- [ ] Summary presented
- [ ] Intelligent next-step analysis presented with integration spike candidates, frontier spike candidates, and standard options
- [ ] Next-step options presented (including frontier spike exploration via `/gsd-spike`)
</success_criteria>

332
get-shit-done/workflows/spike.md
View File

@@ -1,7 +1,11 @@
<purpose>
Rapid feasibility validation through focused, throwaway experiments. Each spike answers one
specific question with observable evidence. Saves artifacts to `.planning/spikes/`.
Companion to `/gsd-spike-wrap-up`.
Spike an idea through experiential exploration — build focused experiments to feel the pieces
of a future app, validate feasibility, and produce verified knowledge for the real build.
Saves artifacts to `.planning/spikes/`. Companion to `/gsd-spike-wrap-up`.
Supports two modes:
- **Idea mode** (default) — user describes an idea to spike
- **Frontier mode** — no argument or "frontier" / "what should I spike?" — analyzes existing spike landscape and proposes integration and frontier spikes
</purpose>
<required_reading>
@@ -20,9 +24,62 @@ Read all files referenced by the invoking prompt's execution_context before star
Parse `$ARGUMENTS` for:
- `--quick` flag → set `QUICK_MODE=true`
- `--text` flag → set `TEXT_MODE=true`
- `frontier` or empty → set `FRONTIER_MODE=true`
- Remaining text → the idea to spike
**Text mode:** If TEXT_MODE is enabled, replace AskUserQuestion calls with plain-text numbered lists — emit the options and ask the user to type the number of their choice.
**Text mode:** If TEXT_MODE is enabled, replace AskUserQuestion calls with plain-text numbered lists.
</step>
<step name="route">
## Routing
- **FRONTIER_MODE is true** → Jump to `frontier_mode`
- **Otherwise** → Continue to `setup_directory`
</step>
<step name="frontier_mode">
## Frontier Mode — Propose What to Spike Next
### Load the Spike Landscape
If no `.planning/spikes/` directory exists, tell the user there's nothing to analyze and offer to start fresh with an idea instead.
Otherwise, load in this order:
**a. MANIFEST.md** — the overall idea, requirements, and spike table with verdicts.
**b. Findings skills** — glob `./.claude/skills/spike-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain curated knowledge from prior wrap-ups.
**c. CONVENTIONS.md** — read `.planning/spikes/CONVENTIONS.md` if it exists. Established stack and patterns.
**d. All spike READMEs** — read `.planning/spikes/*/README.md` for verdicts, results, investigation trails, and tags.
### Analyze for Integration Spikes
Review every pair and cluster of VALIDATED spikes. Look for:
- **Shared resources:** Two spikes that both touch the same API, database, state, or data format but were tested independently.
- **Data handoffs:** Spike A produces output that Spike B consumes. The formats were assumed compatible but never proven.
- **Timing/ordering:** Spikes that work in isolation but have sequencing dependencies in the real flow.
- **Resource contention:** Spikes that individually work but may compete for connections, memory, rate limits, or tokens when combined.
If integration risks exist, present them as concrete proposed spikes with names and Given/When/Then validation questions. If no meaningful integration risks exist, say so and skip this category.
### Analyze for Frontier Spikes
Think laterally about the overall idea from MANIFEST.md and what's been proven so far. Consider:
- **Gaps in the vision:** Capabilities assumed but unproven.
- **Discovered dependencies:** Findings that reveal new questions.
- **Alternative approaches:** Different angles for PARTIAL or INVALIDATED spikes.
- **Adjacent capabilities:** Things that would meaningfully improve the idea if feasible.
- **Comparison opportunities:** Approaches that worked but felt heavy.
Present frontier spikes as concrete proposals numbered from the highest existing spike number with Given/When/Then and risk ordering.
### Get Alignment and Execute
Present all integration and frontier candidates, then ask which to run. When the user picks spikes, write definitions into `.planning/spikes/MANIFEST.md` (appending to existing table) and proceed directly to building them starting at `research`.
</step>
<step name="setup_directory">
@@ -44,13 +101,16 @@ COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true")
</step>
<step name="detect_stack">
Check for the project's tech stack to inform spike technology choices:
Check for the project's tech stack to inform spike technology choices.
**Check conventions first.** If `.planning/spikes/CONVENTIONS.md` exists, follow its stack and patterns — these represent validated choices the user expects to see continued.
**Then check the project stack:**
```bash
ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
```
Use the project's language/framework by default. For greenfield projects with no existing stack, pick whatever gets to a runnable result fastest (Python, Node, Bash, single HTML file).
Use the project's language/framework by default. For greenfield projects with no conventions and no existing stack, pick whatever gets to a runnable result fastest.
Avoid unless the spike specifically requires it:
- Complex package management beyond `npm install` or `pip install`
@@ -59,22 +119,31 @@ Avoid unless the spike specifically requires it:
- Env files or config systems — hardcode everything
</step>
<step name="check_prior_spikes">
If `.planning/spikes/MANIFEST.md` exists, read it. Scan the verdicts, names, and validation questions of all prior spikes. When decomposing the new idea, cross-reference against this history:
<step name="load_prior_context">
If `.planning/spikes/` has existing content, load context in this priority order:
- **Skip already-validated questions.** If a prior spike proved "WebSocket streaming works" with a VALIDATED verdict, don't re-spike it. Note the prior spike number and move on.
- **Build on prior findings.** If a prior spike was INVALIDATED or PARTIAL, factor that into the new decomposition — don't repeat the same approach, and flag the constraint to the user.
- **Call out relevant prior art.** When presenting the decomposition, mention any prior spikes that overlap: "Spike 003 already validated X, so we can skip that and focus on Y."
**a. Conventions:** Read `.planning/spikes/CONVENTIONS.md` if it exists.
If no `.planning/spikes/MANIFEST.md` exists, skip this step.
**b. Findings skills:** Glob for `./.claude/skills/spike-findings-*/SKILL.md` and read any that exist, plus their `references/*.md` files.
**c. Manifest:** Read `.planning/spikes/MANIFEST.md` for the index of all spikes.
**d. Related READMEs:** Based on the new idea, identify which prior spikes are related by matching tags, names, technologies, or domain overlap. Read only those `.planning/spikes/*/README.md` files. Skip unrelated ones.
Cross-reference against this full body of prior work:
- **Skip already-validated questions.** Note the prior spike number and move on.
- **Build on prior findings.** Don't repeat failed approaches. Use their Research and Results sections.
- **Reuse prior research.** Carry findings forward rather than re-researching.
- **Follow established conventions.** Mention any deviation.
- **Call out relevant prior art** when presenting the decomposition.
If no `.planning/spikes/` exists, skip this step.
</step>
<step name="decompose">
**If `QUICK_MODE` is true:** Skip decomposition and alignment. Take the user's idea as a single spike question. Assign it spike number `001` (or next available). Jump to `research`.
**If `QUICK_MODE` is true:** Skip decomposition and alignment. Take the user's idea as a single spike question. Assign it the next available number. Jump to `research`.
**Otherwise:**
Break the idea into 2-5 independent questions that each prove something specific. Frame each as an informal Given/When/Then. Present as a table:
Break the idea into 2-5 independent questions. Frame each as Given/When/Then. Present as a table:
```
| # | Spike | Type | Validates (Given/When/Then) | Risk |
@@ -86,30 +155,17 @@ Break the idea into 2-5 independent questions that each prove something specific
**Spike types:**
- **standard** — one approach answering one question
- **comparison** — same question, different approaches. Use a shared number with lettered variants: `NNN-a-name` and `NNN-b-name`. Both built back-to-back, then head-to-head comparison.
- **comparison** — same question, different approaches. Shared number with letter suffix.
Good spikes answer one specific feasibility question:
- "Can we parse X format and extract Y?" — script that does it on a sample file
- "How fast is X approach?" — benchmark with real-ish data
- "Can we get X and Y to talk to each other?" — thinnest integration
- "What does X feel like as a UI?" — minimal interactive prototype
- "Does X API actually support Y?" — script that calls it and shows the response
- "Should we use X or Y for this?" — **comparison spike**: same thin proof built with both
Good spikes: specific feasibility questions with observable output.
Bad spikes: too broad, no observable output, or just reading/planning.
Bad spikes are too broad or don't produce observable output:
- "Set up the project" — not a question, just busywork
- "Design the architecture" — planning, not spiking
- "Build the backend" — too broad, no specific question
- "Research best practices" — open-ended reading with no runnable output
Order by risk — the spike most likely to kill the idea runs first.
Order by risk — most likely to kill the idea runs first.
</step>
<step name="align">
**If `QUICK_MODE` is true:** Skip.
Present the ordered spike list and ask which to build:
╔══════════════════════════════════════════════════════════════╗
║ CHECKPOINT: Decision Required ║
╚══════════════════════════════════════════════════════════════╝
@@ -119,35 +175,33 @@ Present the ordered spike list and ask which to build:
──────────────────────────────────────────────────────────────
→ Build all in this order, or adjust the list?
──────────────────────────────────────────────────────────────
The user may reorder, merge, split, or skip spikes. Wait for alignment.
</step>
<step name="research">
## Research Before Building
## Research and Briefing Before Each Spike
Before writing any spike code, ground each spike in reality. This prevents building against outdated APIs, picking the wrong library, or discovering mid-spike that the approach is impossible.
This step runs **before each individual spike**, not once at the start.
For each spike about to be built:
**a. Present a spike briefing:**
**a. Identify unknowns.** What libraries, APIs, protocols, or techniques does this spike depend on? What assumptions are you making about how they work?
> **Spike NNN: Descriptive Name**
> [2-3 sentences: what this spike is, why it matters, key risk or unknown.]
**b. Check current docs.** Use context7 (resolve-library-id → query-docs) for any library or framework involved. Use web search for APIs, services, or techniques without a context7 entry. Read actual documentation — not training data, which may be stale.
**b. Research the current state of the art.** Use context7 (resolve-library-id → query-docs) for libraries/frameworks. Use web search for APIs/services without a context7 entry. Read actual documentation.
**c. Validate feasibility before coding.** Specifically check:
- Does the API/library actually support what the spike assumes? (Check endpoints, methods, capabilities)
- What's the current recommended approach? (The "right way" changes — what was learned in training may be deprecated)
- Are there version constraints, breaking changes, or migration gotchas?
- Are there rate limits, auth requirements, or platform restrictions that would block the spike?
**c. Surface competing approaches** as a table:
**d. Pick the right tool.** If multiple libraries could solve the problem, briefly compare them on: current maintenance status, API fit for the specific spike question, and complexity. Pick the one that gets to a runnable answer fastest with the fewest surprises.
| Approach | Tool/Library | Pros | Cons | Status |
|----------|-------------|------|------|--------|
| ... | ... | ... | ... | ... |
**e. Capture research findings.** Add a `## Research` section to the spike's README (before `## How to Run`) with:
- Which docs were checked and key findings
- The chosen approach and why
- Any gotchas or constraints discovered
**Chosen approach:** [which one and why]
**Skip research when unnecessary.** If the spike uses only well-known, stable tools already verified in this session, or if the entire spike is pure logic with no external dependencies, skip this step. The goal is grounding in reality, not busywork.
If 2+ credible approaches exist, plan to build quick variants within the spike and compare them.
**d. Capture research findings** in a `## Research` section in the README.
**Skip when unnecessary** for pure logic with no external dependencies.
</step>
<step name="create_manifest">
@@ -159,57 +213,67 @@ Create or update `.planning/spikes/MANIFEST.md`:
## Idea
[One paragraph describing the overall idea being explored]
## Requirements
[Design decisions that emerged from the user's choices during spiking. Non-negotiable for the real build. Updated as spikes progress.]
- [e.g., "Must use streaming JSON output, not single-response"]
- [e.g., "Must support reconnection on network failure"]
## Spikes
| # | Name | Type | Validates | Verdict | Tags |
|---|------|------|-----------|---------|------|
| 001 | websocket-streaming | standard | WS connections can stream LLM output | VALIDATED | websocket, real-time |
| 002a | pdf-parse-pdfjs | comparison | PDF table extraction | WINNER | pdf, parsing |
| 002b | pdf-parse-camelot | comparison | PDF table extraction | — | pdf, parsing |
```
If MANIFEST.md already exists, append new spikes to the existing table.
**Track requirements as they emerge.** When the user expresses a preference during spiking, add it to the Requirements section immediately.
</step>
<step name="reground">
## Re-Ground Before Each Spike
Before starting each spike (not just the first), re-read `.planning/spikes/MANIFEST.md` and `.planning/spikes/CONVENTIONS.md` to prevent drift within long sessions. Check the Requirements section — make sure the spike doesn't contradict any established requirements.
</step>
<step name="build_spikes">
Build each spike sequentially, highest-risk first.
## Build Each Spike Sequentially
**Comparison spikes** use a shared number with lettered variants: `NNN-a-descriptive-name` and `NNN-b-descriptive-name`. Both answer the same question using different approaches. Build them back-to-back, then report a head-to-head comparison before moving on. Judge on criteria that matter for the real build: API ergonomics, output quality, complexity, performance, or whatever the user cares about. The comparison spike's verdict names the winner and why.
**Depth over speed.** The goal is genuine understanding, not a quick verdict. Never declare VALIDATED after a single happy-path test. Follow surprising findings. Test edge cases. Document the investigation trail, not just the conclusion.
**Comparison spikes** use shared number with letter suffix: `NNN-a-name` / `NNN-b-name`. Build back-to-back, then head-to-head comparison.
### For Each Spike:
**a.** Find next available number by checking existing `.planning/spikes/NNN-*/` directories.
Format: three-digit zero-padded + hyphenated descriptive name. Comparison spikes: same number with letter suffix — `002a-pdf-parse-pdfjs`, `002b-pdf-parse-camelot`.
**a.** Create `.planning/spikes/NNN-descriptive-name/`
**b.** Create the spike directory: `.planning/spikes/NNN-descriptive-name/`
**b.** Assess whether the user needs to experience this spike or Claude can verify alone:
**c.** Assess observability needs before writing code. Ask: **can Claude fully verify this spike's outcome by running a command and reading stdout, or does it require human interaction with a runtime?**
Build interactive prototype when validating:
- Behavior that unfolds over time (streaming, real-time, animations)
- Cause-and-effect sequences (click X → Y happens)
- Data flow between systems
- Visual or presentation quality
- Timing or performance feel
Spikes that need runtime observability:
- **UI spikes** — anything with a browser, clicks, visual feedback
- **Streaming spikes** — WebSockets, SSE, real-time data flow
- **Multi-process spikes** — client/server, IPC, subprocess orchestration
- **Timing-sensitive spikes** — race conditions, debounce, polling, reconnection
- **External API spikes** — where the API response shape, latency, or error behavior matters for the verdict
Stay with stdout/CLI when validating:
- Pure data transformation
- Binary yes/no questions
- Benchmark numbers
- Facts, not feelings
Spikes that do NOT need it:
- Pure computation (parse this file, transform this data)
- Single-run scripts with deterministic stdout
- Anything Claude can run and check the output of directly
**If the spike needs runtime observability,** build a forensic log layer:
1. Event log array with ISO timestamps and category tags
2. Export mechanism (server: GET endpoint, CLI: JSON file, browser: Export button)
3. Log summary (event counts, duration, errors, metadata)
4. Analysis helpers if volume warrants it
**If the spike needs runtime observability,** build a forensic log layer into the spike:
**c.** Build the code. Start with simplest version, then deepen.
1. **An event log array** at module level that captures every meaningful event with an ISO timestamp and a direction/category tag (e.g., `"user_input"`, `"api_response"`, `"sse_frame"`, `"error"`, `"state_change"`)
2. **A log export mechanism** appropriate to the spike's runtime:
- For server spikes: a `GET /api/export-log` endpoint returning downloadable JSON
- For CLI spikes: write `spike-log-{timestamp}.json` to the spike directory on exit or on signal
- For browser spikes: a visible "Export Log" button that triggers a JSON download
3. **A log summary** included in the export: total event counts by category, duration, errors detected, environment metadata
4. **Analysis helpers** if the event volume warrants it: a small script (bash/python) in the spike directory that extracts the signal from the log. Name it `analyze-log.sh` or similar.
**d.** Iterate when findings warrant it:
- **Surprising surface?** Write a follow-up test that isolates and explores it.
- **Answer feels shallow?** Probe edge cases — large inputs, concurrent requests, malformed data, network failures.
- **Assumption wrong?** Adjust. Note the pivot in the README.
Keep the logging lightweight — an array push per event, not a logging framework. Inline it in the spike code.
**d.** Build the minimum code that answers the spike's question (with the observability layer from step c if applicable). Every line must serve the question — nothing incidental.
Multiple files per spike are expected for complex questions (e.g., `test-basic.js`, `test-edge-cases.js`, `benchmark.js`).
**e.** Write `README.md` with YAML frontmatter:
@@ -227,36 +291,38 @@ tags: [tag1, tag2]
# Spike NNN: Descriptive Name
## What This Validates
[The specific feasibility question, framed as Given/When/Then]
[Given/When/Then]
## Research
[Docs checked, key findings, chosen approach and why, gotchas discovered. Omit if no external dependencies.]
[Docs checked, approach comparison table, chosen approach, gotchas. Omit if no external deps.]
## How to Run
[Single command or short sequence to run the spike]
[Command(s)]
## What to Expect
[Concrete observable outcomes: "When you click X, you should see Y within Z seconds"]
[Concrete observable outcomes]
## Observability
[If this spike has a forensic log layer: describe what's captured, how to export the log, and how to analyze it. Omit for spikes without runtime observability.]
[If forensic log layer exists. Omit otherwise.]
## Investigation Trail
[Updated as spike progresses. Document each iteration: what tried, what revealed, what tried next.]
## Results
[Filled in after running — verdict, evidence, surprises. If a forensic log was exported, include key findings from the log analysis here.]
[Verdict, evidence, surprises, log analysis findings.]
```
**f.** Auto-link related spikes: read existing spike READMEs and infer relationships from tags, names, and descriptions. Write the `related` field silently.
**f.** Auto-link related spikes silently.
**g.** Run and verify:
- If self-verifiable: run it, check output, update README verdict and Results section
- If needs human judgment: run it, present instructions using a checkpoint box:
- Self-verifiable: run, iterate if findings warrant deeper investigation, update verdict
- Needs human judgment: present checkpoint box:
╔══════════════════════════════════════════════════════════════╗
║ CHECKPOINT: Verification Required ║
╚══════════════════════════════════════════════════════════════╝
**Spike {NNN}: {name}**
**How to run:** {command}
**What to expect:** {concrete outcomes}
@@ -264,45 +330,69 @@ tags: [tag1, tag2]
→ Does this match what you expected? Describe what you see.
──────────────────────────────────────────────────────────────
- If the spike has a forensic log layer: after verification, export the log and include key findings in the Results section. If something went wrong, ask the user to export the log and provide it for diagnosis.
**h.** Update `.planning/spikes/MANIFEST.md` with the spike's row.
**h.** Update verdict to VALIDATED / INVALIDATED / PARTIAL (or WINNER for comparison spike winners). Update Results section with evidence.
**i.** Update `.planning/spikes/MANIFEST.md` with the spike's row.
**j.** Commit (if `COMMIT_DOCS` is true):
**i.** Commit (if `COMMIT_DOCS` is true):
```bash
gsd-sdk query commit "docs(spike-NNN): [VERDICT] — [key finding in one sentence]" .planning/spikes/NNN-descriptive-name/ .planning/spikes/MANIFEST.md
gsd-sdk query commit "docs(spike-NNN): [VERDICT] — [key finding]" .planning/spikes/NNN-descriptive-name/ .planning/spikes/MANIFEST.md
```
**k.** Report before moving to next spike:
**j.** Report:
```
◆ Spike NNN: {name}
Verdict: {VALIDATED ✓ / INVALIDATED ✗ / PARTIAL ⚠}
Finding: {one sentence}
Impact: {effect on remaining spikes, if any}
Key findings: {not just verdict — investigation trail, surprises, edge cases explored}
Impact: {effect on remaining spikes}
```
**l.** If a spike invalidates a core assumption: stop and present:
Do not rush to a verdict. A spike that says "VALIDATED — it works" with no nuance is almost always incomplete.
**k.** If core assumption invalidated:
╔══════════════════════════════════════════════════════════════╗
║ CHECKPOINT: Decision Required ║
╚══════════════════════════════════════════════════════════════╝
Core assumption invalidated by Spike {NNN}.
{what was invalidated and why}
──────────────────────────────────────────────────────────────
→ Continue with remaining spikes / Pivot approach / Abandon
──────────────────────────────────────────────────────────────
</step>
Only proceed if the user says to.
<step name="update_conventions">
## Update Conventions
After all spikes in this session are built, update `.planning/spikes/CONVENTIONS.md` with patterns that emerged or solidified.
```markdown
# Spike Conventions
Patterns and stack choices established across spike sessions. New spikes follow these unless the question requires otherwise.
## Stack
[What we use for frontend, backend, scripts, and why]
## Structure
[Common file layouts, port assignments, naming patterns]
## Patterns
[Recurring approaches: how we handle auth, how we style, how we serve]
## Tools & Libraries
[Preferred packages with versions that worked, and any to avoid]
```
Only include patterns that repeated across 2+ spikes or were explicitly chosen by the user. If `CONVENTIONS.md` already exists, update sections with new patterns from this session.
Commit (if `COMMIT_DOCS` is true):
```bash
gsd-sdk query commit "docs(spikes): update conventions" .planning/spikes/CONVENTIONS.md
```
</step>
<step name="report">
After all spikes complete, present the consolidated report:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► SPIKE COMPLETE ✓
@@ -314,32 +404,31 @@ After all spikes complete, present the consolidated report:
|---|------|------|---------|
| 001 | {name} | standard | ✓ VALIDATED |
| 002a | {name} | comparison | ✓ WINNER |
| 002b | {name} | comparison | — |
## Key Discoveries
{surprises, gotchas, things that weren't expected}
{surprises, gotchas, investigation trail highlights}
## Feasibility Assessment
{overall, is the idea viable?}
{overall viability}
## Signal for the Build
{what the real implementation should use, avoid, or watch out for}
{what to use, avoid, watch out for}
```
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Package findings** — wrap spike knowledge into a reusable skill
**Package findings** — wrap spike knowledge into an implementation blueprint
`/gsd-spike-wrap-up`
───────────────────────────────────────────────────────────────
**Also available:**
- `/gsd-spike` — spike more ideas (or run with no argument for frontier mode)
- `/gsd-plan-phase` — start planning the real implementation
- `/gsd-explore` — continue exploring the idea
- `/gsd-add-phase` — add a phase to the roadmap based on findings
───────────────────────────────────────────────────────────────
</step>
@@ -348,15 +437,16 @@ After all spikes complete, present the consolidated report:
<success_criteria>
- [ ] `.planning/spikes/` created (auto-creates if needed, no project init required)
- [ ] Prior spikes checked — already-validated questions skipped, prior findings factored in
- [ ] Research grounded each spike in current docs before coding (unless pure logic/no deps)
- [ ] Prior spikes and findings skills consulted before building
- [ ] Conventions followed (or deviation documented)
- [ ] Research grounded each spike in current docs before coding
- [ ] Depth over speed — edge cases tested, surprising findings followed, investigation trail documented
- [ ] Comparison spikes built back-to-back with head-to-head verdict
- [ ] Spikes needing human interaction have forensic log layer (event capture, export, analysis)
- [ ] Each spike answers one specific question with observable evidence
- [ ] Each spike README has complete frontmatter (including type), run instructions, and results
- [ ] User verified each spike (self-verified or human checkpoint)
- [ ] MANIFEST.md is current (with Type column)
- [ ] Spikes needing human interaction have forensic log layer
- [ ] Requirements tracked in MANIFEST.md as they emerge from user choices
- [ ] CONVENTIONS.md created or updated with patterns that emerged
- [ ] Each spike README has complete frontmatter, Investigation Trail, and Results
- [ ] MANIFEST.md is current (with Type column and Requirements section)
- [ ] Commits use `docs(spike-NNN): [VERDICT]` format
- [ ] Consolidated report presented with next-step routing
- [ ] If core assumption invalidated, execution stopped and user consulted
</success_criteria>