From c86ca1b3eb2016488dcef2299b10ea04fe484bb2 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Tue, 21 Apr 2026 09:05:11 -0600 Subject: [PATCH] fix: sync spike/sketch workflows with upstream skill v2 improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- commands/gsd/sketch.md | 17 +- commands/gsd/spike.md | 22 +- get-shit-done/workflows/sketch-wrap-up.md | 10 +- get-shit-done/workflows/sketch.md | 147 ++++++++-- get-shit-done/workflows/spike-wrap-up.md | 171 +++++++----- get-shit-done/workflows/spike.md | 322 +++++++++++++++++----- 6 files changed, 510 insertions(+), 179 deletions(-) diff --git a/commands/gsd/sketch.md b/commands/gsd/sketch.md index 0f9ae883b..8d3e543a7 100644 --- a/commands/gsd/sketch.md +++ b/commands/gsd/sketch.md @@ -1,7 +1,7 @@ --- name: gsd:sketch -description: Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration -argument-hint: " [--quick]" +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 @@ -10,11 +10,20 @@ allowed-tools: - Grep - Glob - AskUserQuestion + - WebSearch + - WebFetch + - mcp__context7__resolve-library-id + - mcp__context7__query-docs --- 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. @@ -41,5 +50,5 @@ Design idea: $ARGUMENTS Execute the sketch workflow from @~/.claude/get-shit-done/workflows/sketch.md end-to-end. -Preserve all workflow gates (intake, decomposition, variant evaluation, MANIFEST updates, commit patterns). +Preserve all workflow gates (intake, decomposition, target stack research, variant evaluation, MANIFEST updates, commit patterns). diff --git a/commands/gsd/spike.md b/commands/gsd/spike.md index 05f5de96d..762238c9f 100644 --- a/commands/gsd/spike.md +++ b/commands/gsd/spike.md @@ -1,7 +1,7 @@ --- name: gsd:spike -description: Rapidly spike an idea with throwaway experiments to validate feasibility before planning -argument-hint: " [--quick]" +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 @@ -10,11 +10,20 @@ allowed-tools: - Grep - Glob - AskUserQuestion + - WebSearch + - WebFetch + - mcp__context7__resolve-library-id + - mcp__context7__query-docs --- -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. @@ -33,9 +42,10 @@ Idea: $ARGUMENTS **Available flags:** - `--quick` — Skip decomposition/alignment, jump straight to building. Use when you already know what to spike. +- `--text` — Use plain-text numbered lists instead of AskUserQuestion (for non-Claude runtimes). Execute the spike workflow from @~/.claude/get-shit-done/workflows/spike.md end-to-end. -Preserve all workflow gates (decomposition, risk ordering, verification, MANIFEST updates, commit patterns). +Preserve all workflow gates (prior spike check, decomposition, research, risk ordering, observability assessment, verification, MANIFEST updates, commit patterns). diff --git a/get-shit-done/workflows/sketch-wrap-up.md b/get-shit-done/workflows/sketch-wrap-up.md index 1f12b48a7..6ae4bbf7b 100644 --- a/get-shit-done/workflows/sketch-wrap-up.md +++ b/get-shit-done/workflows/sketch-wrap-up.md @@ -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`) diff --git a/get-shit-done/workflows/sketch.md b/get-shit-done/workflows/sketch.md index 72f8e1bcf..335d69362 100644 --- a/get-shit-done/workflows/sketch.md +++ b/get-shit-done/workflows/sketch.md @@ -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 @@ -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. + + + +## Routing + +- **FRONTIER_MODE is true** → Jump to `frontier_mode` +- **Otherwise** → Continue to `setup_directory` + + + +## 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`. @@ -49,27 +104,45 @@ COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true") -**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:** -**Text mode:** If TEXT_MODE is enabled (set in the banner step), replace AskUserQuestion calls with plain-text numbered lists — emit the options and ask the user to type the number of their choice. - -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 — 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. + +## 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. + + Break the idea into 2-5 design questions. Present as a table: @@ -92,6 +165,28 @@ Bad sketches: Present the table and get alignment before building. + +## Research the Target Stack + +Before sketching, ground the design in what's actually buildable. Sketches are HTML, but they should reflect real constraints of the target implementation. + +**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? +- Are there existing component libraries in use? What components are available? +- What interaction patterns are idiomatic? + +**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.** At least one variant should follow the path of least resistance for the target stack. + +**Skip when unnecessary.** Greenfield project with no stack, or user says "just explore visually." The point is grounding, not gatekeeping. + + Create or update `.planning/sketches/MANIFEST.md`: @@ -124,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`: @@ -190,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 @@ -215,7 +308,7 @@ gsd-sdk query commit "docs(sketch-NNN): [winning direction] — [key visual insi -After all sketches complete, present the summary: +After all sketches complete: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -243,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 ─────────────────────────────────────────────────────────────── @@ -255,7 +348,9 @@ After all sketches complete, present the summary: - [ ] `.planning/sketches/` created (auto-creates if needed, no project init required) - [ ] Design direction explored conversationally before any code (unless --quick) -- [ ] Each sketch has 2-3 variants for comparison +- [ ] 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) diff --git a/get-shit-done/workflows/spike-wrap-up.md b/get-shit-done/workflows/spike-wrap-up.md index ce543cc39..46c03aeb8 100644 --- a/get-shit-done/workflows/spike-wrap-up.md +++ b/get-shit-done/workflows/spike-wrap-up.md @@ -1,8 +1,8 @@ -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`. @@ -22,7 +22,7 @@ Read all files referenced by the invoking prompt's execution_context before star ## 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 @@ -41,53 +41,28 @@ COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true") ``` - -## Curate Spikes One-at-a-Time + +## Auto-Include All Spikes -Present each unprocessed spike in ascending order. For each spike, show: +Include all unprocessed spikes automatically. Present a brief inventory showing what's being processed: -- **Spike number and name** -- **Validates:** the Given/When/Then from frontmatter -- **Verdict:** VALIDATED / INVALIDATED / PARTIAL -- **Tags:** from frontmatter -- **Key findings:** summarize the Results section from the README -- **Grey areas:** anything uncertain or partially proven +``` +Processing N spikes: + 001 — name (VALIDATED) + 002 — name (PARTIAL) + 003 — name (INVALIDATED) +``` -Then ask the user: - -╔══════════════════════════════════════════════════════════════╗ -║ CHECKPOINT: Decision Required ║ -╚══════════════════════════════════════════════════════════════╝ - -Spike {NNN}: {name} — {verdict} - -{key findings summary} - -────────────────────────────────────────────────────────────── -→ Include / Exclude / Partial / Help me UAT this -────────────────────────────────────────────────────────────── - -**If "Help me UAT this":** -1. Read the spike's README "How to Run" and "What to Expect" sections -2. Present step-by-step instructions -3. Ask: "Does this match what you expected?" -4. After UAT, return to the include/exclude/partial decision - -**If "Partial":** -Ask what specifically to include or exclude. Record their notes alongside the spike. +Every spike carries forward: +- **VALIDATED** spikes provide proven patterns +- **PARTIAL** spikes provide constrained patterns +- **INVALIDATED** spikes provide landmines and dead ends ## Auto-Group by Feature Area -After all spikes are curated: - -1. Read all included spikes' tags, names, `related` fields, and content -2. Propose feature-area groupings, e.g.: - - "**WebSocket Streaming** — spikes 001, 004, 007" - - "**Foo API Integration** — spikes 002, 003" - - "**PDF Parsing** — spike 005" -3. Present the grouping for approval — user may merge, split, rename, or rearrange +Group spikes by feature area based on tags, names, `related` fields, and content. Proceed directly into synthesis. Each group becomes one reference file in the generated skill. @@ -118,21 +93,29 @@ For each included spike: ## 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/ ``` @@ -146,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. --- @@ -157,6 +140,15 @@ description: Validated patterns, constraints, and implementation knowledge from Spike sessions wrapped: [date(s)] + +## 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] + + ## Feature Areas @@ -193,13 +185,9 @@ Write `.planning/spikes/WRAP-UP-SUMMARY.md` for project history: **Feature areas:** [list] **Skill output:** `./.claude/skills/spike-findings-[project]/` -## Included Spikes -| # | Name | Verdict | Feature Area | -|---|------|---------|--------------| - -## Excluded Spikes -| # | Name | Reason | -|---|------|--------| +## Processed Spikes +| # | Name | Type | Verdict | Feature Area | +|---|------|------|---------|--------------| ## Key Findings [consolidated findings summary] @@ -218,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. + +## 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. + + 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 ``` @@ -232,29 +256,37 @@ gsd-sdk query commit "docs(spike-wrap-up): package [N] spike findings into proje GSD ► SPIKE WRAP-UP COMPLETE ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -**Curated:** {N} spikes ({included} included, {excluded} excluded) +**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 The spike-findings skill will auto-load in future build conversations. ``` + + + +## What's Next + +After the summary, present next-step options: ─────────────────────────────────────────────────────────────── ## ▶ Next Up -**Start building** — plan the real implementation +**Explore frontier spikes** — see what else is worth spiking based on what we've learned -`/gsd-plan-phase` +`/gsd-spike` (run with no argument — its frontier mode analyzes the spike landscape and proposes integration and frontier spikes) ─────────────────────────────────────────────────────────────── **Also available:** -- `/gsd-add-phase` — add a phase based on spike findings -- `/gsd-spike` — spike additional ideas +- `/gsd-plan-phase` — start planning the real implementation +- `/gsd-spike [idea]` — spike a specific new idea - `/gsd-explore` — continue exploring +- Other ─────────────────────────────────────────────────────────────── @@ -262,12 +294,13 @@ The spike-findings skill will auto-load in future build conversations. -- [ ] Every unprocessed spike presented for individual curation -- [ ] Feature-area grouping proposed and approved -- [ ] Spike-findings skill exists at `./.claude/skills/` with SKILL.md, references/, sources/ -- [ ] Core source files from included spikes copied into sources/ -- [ ] Reference files contain validated patterns, code snippets, landmines, constraints +- [ ] All unprocessed spikes auto-included and processed +- [ ] Spikes grouped by feature area +- [ ] 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 with next-step routing +- [ ] Summary presented +- [ ] Next-step options presented (including frontier spike exploration via `/gsd-spike`) diff --git a/get-shit-done/workflows/spike.md b/get-shit-done/workflows/spike.md index f2db5752f..03a292ea2 100644 --- a/get-shit-done/workflows/spike.md +++ b/get-shit-done/workflows/spike.md @@ -1,7 +1,11 @@ -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 @@ -19,7 +23,63 @@ 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. + + + +## Routing + +- **FRONTIER_MODE is true** → Jump to `frontier_mode` +- **Otherwise** → Continue to `setup_directory` + + + +## 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`. @@ -41,13 +101,16 @@ COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true") -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` @@ -56,40 +119,53 @@ Avoid unless the spike specifically requires it: - Env files or config systems — hardcode everything + +If `.planning/spikes/` has existing content, load context in this priority order: + +**a. Conventions:** Read `.planning/spikes/CONVENTIONS.md` if it exists. + +**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. + + -**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 `build_spikes`. +**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 | Validates (Given/When/Then) | Risk | -|---|-------|-----------------------------|------| -| 001 | websocket-streaming | Given a WS connection, when LLM streams tokens, then client receives chunks < 100ms | **High** | -| 002 | pdf-extraction | Given a multi-page PDF, when parsed with pdfjs, then structured text is extractable | Medium | +| # | Spike | Type | Validates (Given/When/Then) | Risk | +|---|-------|------|-----------------------------|------| +| 001 | websocket-streaming | standard | Given a WS connection, when LLM streams tokens, then client receives chunks < 100ms | **High** | +| 002a | pdf-parse-pdfjs | comparison | Given a multi-page PDF, when parsed with pdfjs, then structured text is extractable | Medium | +| 002b | pdf-parse-camelot | comparison | Given a multi-page PDF, when parsed with camelot, then structured text is extractable | Medium | ``` -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 +**Spike types:** +- **standard** — one approach answering one question +- **comparison** — same question, different approaches. Shared number with letter suffix. -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 +Good spikes: specific feasibility questions with observable output. +Bad spikes: too broad, no observable output, or just reading/planning. -Order by risk — the spike most likely to kill the idea runs first. +Order by risk — most likely to kill the idea runs first. **If `QUICK_MODE` is true:** Skip. -Present the ordered spike list and ask which to build: - ╔══════════════════════════════════════════════════════════════╗ ║ CHECKPOINT: Decision Required ║ ╚══════════════════════════════════════════════════════════════╝ @@ -99,8 +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. + +## Research and Briefing Before Each Spike + +This step runs **before each individual spike**, not once at the start. + +**a. Present a spike briefing:** + +> **Spike NNN: Descriptive Name** +> [2-3 sentences: what this spike is, why it matters, key risk or unknown.] + +**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. Surface competing approaches** as a table: + +| Approach | Tool/Library | Pros | Cons | Status | +|----------|-------------|------|------|--------| +| ... | ... | ... | ... | ... | + +**Chosen approach:** [which one and why] + +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. @@ -112,33 +213,75 @@ 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 | Validates | Verdict | Tags | -|---|------|-----------|---------|------| +| # | Name | Type | Validates | Verdict | Tags | +|---|------|------|-----------|---------|------| ``` -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. + + + +## 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. -Build each spike sequentially, highest-risk first. +## Build Each Spike Sequentially + +**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. +**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.** Build the minimum code that answers the spike's question. Every line must serve the question — nothing incidental. If auth isn't the question, hardcode a token. If the database isn't the question, use a JSON file. Strip everything that doesn't directly answer "does X work?" +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 -**d.** Write `README.md` with YAML frontmatter: +Stay with stdout/CLI when validating: +- Pure data transformation +- Binary yes/no questions +- Benchmark numbers +- Facts, not feelings + +**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 + +**c.** Build the code. Start with simplest version, then deepen. + +**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. + +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: ```markdown --- spike: NNN name: descriptive-name +type: standard validates: "Given [precondition], when [action], then [expected outcome]" verdict: PENDING related: [] @@ -148,30 +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, 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 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] +[Verdict, evidence, surprises, log analysis findings.] ``` -**e.** 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. -**f.** 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: +**g.** Run and verify: +- 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} @@ -179,43 +330,69 @@ tags: [tag1, tag2] → Does this match what you expected? Describe what you see. ────────────────────────────────────────────────────────────── -**g.** Update verdict to VALIDATED / INVALIDATED / PARTIAL. Update Results section with evidence. - **h.** Update `.planning/spikes/MANIFEST.md` with the spike's row. **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 ``` -**j.** 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} ``` -**k.** 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 ────────────────────────────────────────────────────────────── + -Only proceed if the user says to. + +## 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 +``` -After all spikes complete, present the consolidated report: - ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► SPIKE COMPLETE ✓ @@ -223,35 +400,35 @@ After all spikes complete, present the consolidated report: ## Verdicts -| # | Name | Verdict | -|---|------|---------| -| 001 | {name} | ✓ VALIDATED | -| 002 | {name} | ✗ INVALIDATED | +| # | Name | Type | Verdict | +|---|------|------|---------| +| 001 | {name} | standard | ✓ VALIDATED | +| 002a | {name} | comparison | ✓ WINNER | ## 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 ─────────────────────────────────────────────────────────────── @@ -260,11 +437,16 @@ After all spikes complete, present the consolidated report: - [ ] `.planning/spikes/` created (auto-creates if needed, no project init required) -- [ ] Each spike answers one specific question with observable evidence -- [ ] Each spike README has complete frontmatter, run instructions, and results -- [ ] User verified each spike (self-verified or human checkpoint) -- [ ] MANIFEST.md is current +- [ ] 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 +- [ ] 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