diff --git a/commands/gsd/sketch-wrap-up.md b/commands/gsd/sketch-wrap-up.md new file mode 100644 index 000000000..bebabab44 --- /dev/null +++ b/commands/gsd/sketch-wrap-up.md @@ -0,0 +1,31 @@ +--- +name: gsd:sketch-wrap-up +description: Package sketch design findings into a persistent project skill for future build conversations +allowed-tools: + - Read + - Write + - Edit + - Bash + - Grep + - Glob + - AskUserQuestion +--- + +Curate sketch design findings and package them into a persistent project skill that Claude +auto-loads when building the real UI. Also writes a summary to `.planning/sketches/` for +project history. Output skill goes to `./.claude/skills/sketch-findings-[project]/` (project-local). + + + +@~/.claude/get-shit-done/workflows/sketch-wrap-up.md +@~/.claude/get-shit-done/references/ui-brand.md + + + +**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. + + + +Execute the sketch-wrap-up workflow from @~/.claude/get-shit-done/workflows/sketch-wrap-up.md end-to-end. +Preserve all curation gates (per-sketch review, grouping approval, CLAUDE.md routing line). + diff --git a/commands/gsd/sketch.md b/commands/gsd/sketch.md new file mode 100644 index 000000000..0f9ae883b --- /dev/null +++ b/commands/gsd/sketch.md @@ -0,0 +1,45 @@ +--- +name: gsd:sketch +description: Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration +argument-hint: " [--quick]" +allowed-tools: + - Read + - Write + - Edit + - Bash + - Grep + - Glob + - AskUserQuestion +--- + +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. + +Does not require `/gsd-new-project` — auto-creates `.planning/sketches/` if needed. + + + +@~/.claude/get-shit-done/workflows/sketch.md +@~/.claude/get-shit-done/references/ui-brand.md +@~/.claude/get-shit-done/references/sketch-theme-system.md +@~/.claude/get-shit-done/references/sketch-interactivity.md +@~/.claude/get-shit-done/references/sketch-tooling.md +@~/.claude/get-shit-done/references/sketch-variant-patterns.md + + + +**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. + + + +Design idea: $ARGUMENTS + +**Available flags:** +- `--quick` — Skip mood/direction intake, jump straight to decomposition and building. Use when the design direction is already clear. + + + +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). + diff --git a/commands/gsd/spike-wrap-up.md b/commands/gsd/spike-wrap-up.md new file mode 100644 index 000000000..5baaf6591 --- /dev/null +++ b/commands/gsd/spike-wrap-up.md @@ -0,0 +1,31 @@ +--- +name: gsd:spike-wrap-up +description: Package spike findings into a persistent project skill for future build conversations +allowed-tools: + - Read + - Write + - Edit + - Bash + - Grep + - Glob + - AskUserQuestion +--- + +Curate spike experiment findings and package them into a persistent project skill that Claude +auto-loads in future build conversations. Also writes a summary to `.planning/spikes/` for +project history. Output skill goes to `./.claude/skills/spike-findings-[project]/` (project-local). + + + +@~/.claude/get-shit-done/workflows/spike-wrap-up.md +@~/.claude/get-shit-done/references/ui-brand.md + + + +**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. + + + +Execute the spike-wrap-up workflow from @~/.claude/get-shit-done/workflows/spike-wrap-up.md end-to-end. +Preserve all curation gates (per-spike review, grouping approval, CLAUDE.md routing line). + diff --git a/commands/gsd/spike.md b/commands/gsd/spike.md new file mode 100644 index 000000000..05f5de96d --- /dev/null +++ b/commands/gsd/spike.md @@ -0,0 +1,41 @@ +--- +name: gsd:spike +description: Rapidly spike an idea with throwaway experiments to validate feasibility before planning +argument-hint: " [--quick]" +allowed-tools: + - Read + - Write + - Edit + - Bash + - Grep + - Glob + - AskUserQuestion +--- + +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. + +Does not require `/gsd-new-project` — auto-creates `.planning/spikes/` if needed. + + + +@~/.claude/get-shit-done/workflows/spike.md +@~/.claude/get-shit-done/references/ui-brand.md + + + +**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. + + + +Idea: $ARGUMENTS + +**Available flags:** +- `--quick` — Skip decomposition/alignment, jump straight to building. Use when you already know what to spike. + + + +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). + diff --git a/get-shit-done/references/artifact-types.md b/get-shit-done/references/artifact-types.md index e1f57a9e3..d472c32fd 100644 --- a/get-shit-done/references/artifact-types.md +++ b/get-shit-done/references/artifact-types.md @@ -72,6 +72,24 @@ reads is inert — the consumption mechanism is what gives an artifact meaning. - **Location**: `.planning/spikes/SPIKE-NNN/` - **Consumed by**: Planner when spike is referenced; `pause-work` for spike context handoff +### Spike README.md / MANIFEST.md (per-spike, via /gsd-spike) +- **Shape**: YAML frontmatter (spike, name, validates, verdict, related, tags) + run instructions + results +- **Lifecycle**: Created by `/gsd-spike` → Verified → Wrapped up by `/gsd-spike-wrap-up` +- **Location**: `.planning/spikes/NNN-name/README.md`, `.planning/spikes/MANIFEST.md` +- **Consumed by**: `/gsd-spike-wrap-up` for curation; `pause-work` for spike context handoff + +### Sketch README.md / MANIFEST.md / index.html (per-sketch) +- **Shape**: YAML frontmatter (sketch, name, question, winner, tags) + variants as tabbed HTML +- **Lifecycle**: Created by `/gsd-sketch` → Evaluated → Wrapped up by `/gsd-sketch-wrap-up` +- **Location**: `.planning/sketches/NNN-name/README.md`, `.planning/sketches/NNN-name/index.html`, `.planning/sketches/MANIFEST.md` +- **Consumed by**: `/gsd-sketch-wrap-up` for curation; `pause-work` for sketch context handoff + +### WRAP-UP-SUMMARY.md (per wrap-up session) +- **Shape**: Curation results, included/excluded items, feature/design area groupings +- **Lifecycle**: Created by `/gsd-spike-wrap-up` or `/gsd-sketch-wrap-up` +- **Location**: `.planning/spikes/WRAP-UP-SUMMARY.md` or `.planning/sketches/WRAP-UP-SUMMARY.md` +- **Consumed by**: Project history; not read by automated workflows + --- ## Standing Reference Artifacts diff --git a/get-shit-done/references/sketch-interactivity.md b/get-shit-done/references/sketch-interactivity.md new file mode 100644 index 000000000..8063464b5 --- /dev/null +++ b/get-shit-done/references/sketch-interactivity.md @@ -0,0 +1,41 @@ +# Making Sketches Feel Alive + +Static mockups are barely better than screenshots. Every interactive element in a sketch must respond to interaction. + +## Required Interactivity + +| Element | Must Have | +|---------|-----------| +| Buttons | Click handler with visible feedback (state change, animation, toast) | +| Forms | Input validation on blur, submit handler that shows success state | +| Lists | Add/remove items, empty state, populated state | +| Toggles/switches | Working toggle with visible state change | +| Tabs/nav | Click to switch content | +| Modals/drawers | Open/close with transition | +| Hover states | Every clickable element needs a hover effect | +| Dropdowns | Open/close, item selection | + +## Transitions + +Add `transition: all 0.15s ease` as a baseline to interactive elements. Subtle motion makes the sketch feel real and helps judge whether the interaction pattern works. + +## Fake the Backend + +If the sketch shows a "Save" button, clicking it should show a brief loading state then a success message. If it shows a search bar, typing should filter hardcoded results. The goal is to feel the full interaction loop, not just see the resting state. + +## State Cycling + +If the sketch has multiple states (empty, loading, populated, error), include buttons to cycle through them. Label each state clearly. This lets the user experience how the design handles different data conditions. + +## Implementation + +Use vanilla JS in inline ` +``` diff --git a/get-shit-done/references/sketch-theme-system.md b/get-shit-done/references/sketch-theme-system.md new file mode 100644 index 000000000..57cb97082 --- /dev/null +++ b/get-shit-done/references/sketch-theme-system.md @@ -0,0 +1,94 @@ +# Shared Theme System + +All sketches share a CSS variable theme so design decisions compound across sketches. + +## Setup + +On the first sketch, create `.planning/sketches/themes/` with a default theme: + +``` +.planning/sketches/ + themes/ + default.css <- all sketches link to this + 001-dashboard-layout/ + index.html <- links to ../themes/default.css +``` + +## Theme File Structure + +Each theme defines CSS custom properties only — no component styles, no layout rules. Just the visual vocabulary: + +```css +:root { + /* Colors */ + --color-bg: #fafafa; + --color-surface: #ffffff; + --color-border: #e5e5e5; + --color-text: #1a1a1a; + --color-text-muted: #6b6b6b; + --color-primary: #2563eb; + --color-primary-hover: #1d4ed8; + --color-accent: #f59e0b; + --color-danger: #ef4444; + --color-success: #22c55e; + + /* Typography */ + --font-sans: 'Inter', system-ui, sans-serif; + --font-mono: 'JetBrains Mono', monospace; + --text-xs: 0.75rem; + --text-sm: 0.875rem; + --text-base: 1rem; + --text-lg: 1.125rem; + --text-xl: 1.25rem; + --text-2xl: 1.5rem; + --text-3xl: 1.875rem; + + /* Spacing */ + --space-1: 4px; + --space-2: 8px; + --space-3: 12px; + --space-4: 16px; + --space-6: 24px; + --space-8: 32px; + --space-12: 48px; + + /* Shapes */ + --radius-sm: 4px; + --radius-md: 8px; + --radius-lg: 12px; + --radius-full: 9999px; + + /* Shadows */ + --shadow-sm: 0 1px 2px rgba(0,0,0,0.05); + --shadow-md: 0 4px 6px rgba(0,0,0,0.07); + --shadow-lg: 0 10px 15px rgba(0,0,0,0.1); +} +``` + +Adapt the default theme to match the mood/direction established during intake. The values above are a starting point — change colors, fonts, spacing, and shapes to match the agreed aesthetic. + +## Linking + +Every sketch links to the theme: + +```html + +``` + +## Creating New Themes + +When a sketch reveals an aesthetic fork ("should this feel clinical or warm?"), create both as theme files rather than arguing about it. The user can switch and feel the difference. + +Name themes descriptively: `midnight.css`, `warm-minimal.css`, `brutalist.css`. + +## Theme Switcher + +Include in every sketch (part of the sketch toolbar): + +```html + +``` + +Dynamically populate options by listing available theme files, or hardcode the known themes. diff --git a/get-shit-done/references/sketch-tooling.md b/get-shit-done/references/sketch-tooling.md new file mode 100644 index 000000000..05959eefd --- /dev/null +++ b/get-shit-done/references/sketch-tooling.md @@ -0,0 +1,45 @@ +# Sketch Toolbar + +Include a small floating toolbar in every sketch. It provides utilities without competing with the actual design. + +## Implementation + +A small `
` fixed to the bottom-right, semi-transparent, expands on hover: + +```html +
+ + + +
+``` + +## Components + +### Theme Switcher + +A dropdown that swaps the theme CSS file at runtime: + +```html + +``` + +### Viewport Preview + +Three buttons that constrain the sketch content area to standard widths: + +- Phone: 375px +- Tablet: 768px +- Desktop: 1280px (or full width) + +Implemented by wrapping sketch content in a container and adjusting its `max-width`. + +### Annotation Mode + +A toggle that overlays spacing values, color hex codes, and font sizes on hover. Implemented as a JS snippet that reads computed styles and shows them in a tooltip. Helps understand visual decisions without opening dev tools. + +## Styling + +The toolbar should be unobtrusive — small, dark, semi-transparent. It should never compete with the sketch visually. Style it independently of the theme (hardcoded dark background, white text). diff --git a/get-shit-done/references/sketch-variant-patterns.md b/get-shit-done/references/sketch-variant-patterns.md new file mode 100644 index 000000000..a89fc826f --- /dev/null +++ b/get-shit-done/references/sketch-variant-patterns.md @@ -0,0 +1,81 @@ +# Multi-Variant HTML Patterns + +Every sketch produces 2-3 variants in the same HTML file. The user switches between them to compare. + +## Tab-Based Variants + +The standard approach: a tab bar at the top of the page, each tab shows a different variant. + +```html +
+ + + +
+ +
+ +
+ + + + +``` + +Add `padding-top` to the body to account for the fixed tab bar. + +## Marking the Winner + +After the user picks a direction, add a visual indicator to the winning tab: + +```html + +``` + +Keep all variants visible and navigable — the winner is highlighted, not the only option. + +## Side-by-Side (for small variants) + +When comparing small elements (button styles, card layouts, icon treatments), render them next to each other with labels rather than using tabs: + +```html +
+
+

A: Rounded

+ +
+
+

B: Sharp

+ +
+
+

C: Pill

+ +
+
+``` + +## Variant Count + +- **First round (dramatic):** 2-3 meaningfully different approaches +- **Refinement rounds:** 2-3 subtle variations within the chosen direction +- **Never more than 4** — more than that overwhelms. If there are 5+ options, narrow before showing. + +## Synthesis Variants + +When the user cherry-picks elements across variants, create a new variant tab labeled descriptively: + +```html + +``` diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index d85e46b2b..ec21ef643 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/get-shit-done/workflows/discuss-phase.md @@ -348,9 +348,40 @@ Structure the extracted information: ``` +**Step 4: Load spike/sketch findings (if they exist)** +```bash +# Check for spike/sketch findings skills (project-local) +SPIKE_FINDINGS=$(ls ./.claude/skills/spike-findings-*/SKILL.md 2>/dev/null | head -1) +SKETCH_FINDINGS=$(ls ./.claude/skills/sketch-findings-*/SKILL.md 2>/dev/null | head -1) + +# Also check for raw spikes/sketches not yet wrapped up +RAW_SPIKES=$(ls .planning/spikes/MANIFEST.md 2>/dev/null) +RAW_SKETCHES=$(ls .planning/sketches/MANIFEST.md 2>/dev/null) +``` + +If spike/sketch findings skills exist, read their SKILL.md and reference files. Extract: +- **Validated patterns** — what was proven to work (use these, don't re-explore) +- **Landmines** — what was proven NOT to work (avoid these) +- **Constraints** — hard limits discovered (rate limits, API gaps, library limitations) +- **Design decisions** — winning visual directions, CSS patterns, layout choices + +Add to ``: +``` +## From Spike Experiments +- [Validated pattern or constraint from spike findings] + +## From Design Sketches +- [Design decision or visual direction from sketch findings] +``` + +If raw spikes/sketches exist but no findings skill, note in output: +``` +⚠ Unpackaged spikes/sketches detected — run `/gsd-spike-wrap-up` or `/gsd-sketch-wrap-up` to make findings available to planning agents. +``` + **Usage in subsequent steps:** -- `analyze_phase`: Skip gray areas already decided in prior phases -- `present_gray_areas`: Annotate options with prior decisions ("You chose X in Phase 5") +- `analyze_phase`: Skip gray areas already decided in prior phases or validated by spikes/sketches +- `present_gray_areas`: Annotate options with prior decisions ("You chose X in Phase 5") and spike/sketch findings ("Spike 002 validated this approach") - `discuss_areas`: Pre-fill answers or flag conflicts ("This contradicts Phase 3 — same here or different?") **If no prior context exists:** Continue without — this is expected for early phases. diff --git a/get-shit-done/workflows/do.md b/get-shit-done/workflows/do.md index 89c8e337b..4eca2a47e 100644 --- a/get-shit-done/workflows/do.md +++ b/get-shit-done/workflows/do.md @@ -42,6 +42,10 @@ Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching** | Starting a new project, "set up", "initialize" | `/gsd-new-project` | Needs full project initialization | | Mapping or analyzing an existing codebase | `/gsd-map-codebase` | Codebase discovery | | A bug, error, crash, failure, or something broken | `/gsd-debug` | Needs systematic investigation | +| Spiking, "test if", "will this work", "experiment", "prove this out", validate feasibility | `/gsd-spike` | Throwaway experiment to validate feasibility | +| Sketching, "mockup", "what would this look like", "prototype the UI", "design this", explore visual direction | `/gsd-sketch` | Throwaway HTML mockups to explore design | +| Wrapping up spikes, "package the spikes", "consolidate spike findings" | `/gsd-spike-wrap-up` | Package spike findings into reusable skill | +| Wrapping up sketches, "package the designs", "consolidate sketch findings" | `/gsd-sketch-wrap-up` | Package sketch findings into reusable skill | | Exploring, researching, comparing, or "how does X work" | `/gsd-research-phase` | Domain research before planning | | Discussing vision, "how should X look", brainstorming | `/gsd-discuss-phase` | Needs context gathering | | A complex task: refactoring, migration, multi-file architecture, system redesign | `/gsd-add-phase` | Needs a full phase with plan/build cycle | @@ -56,7 +60,7 @@ Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching** | Completing a milestone, shipping, releasing | `/gsd-complete-milestone` | Milestone lifecycle | | A specific, actionable, small task (add feature, fix typo, update config) | `/gsd-quick` | Self-contained, single executor | -**Requires `.planning/` directory:** All routes except `/gsd-new-project`, `/gsd-map-codebase`, `/gsd-help`, and `/gsd-join-discord`. If the project doesn't exist and the route requires it, suggest `/gsd-new-project` first. +**Requires `.planning/` directory:** All routes except `/gsd-new-project`, `/gsd-map-codebase`, `/gsd-spike`, `/gsd-sketch`, `/gsd-help`, and `/gsd-join-discord`. If the project doesn't exist and the route requires it, suggest `/gsd-new-project` first. **Ambiguity handling:** If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example: diff --git a/get-shit-done/workflows/explore.md b/get-shit-done/workflows/explore.md index ecb8d9d8d..444859f30 100644 --- a/get-shit-done/workflows/explore.md +++ b/get-shit-done/workflows/explore.md @@ -82,6 +82,8 @@ When the conversation reaches natural conclusions or the developer signals readi | Research question | `.planning/research/questions.md` (append) | Open questions that need deeper investigation | | Requirement | `REQUIREMENTS.md` (append) | Clear requirements that emerged from discussion | | New phase | `ROADMAP.md` (append) | Scope large enough to warrant its own phase | +| Spike | `/gsd-spike` (invoke) | Feasibility uncertainty surfaced — "will this API work?", "can we do X?" | +| Sketch | `/gsd-sketch` (invoke) | Design direction unclear — "what should this look like?", "how should this feel?" | Present suggestions: ``` diff --git a/get-shit-done/workflows/help.md b/get-shit-done/workflows/help.md index e23b13144..8ce8f620a 100644 --- a/get-shit-done/workflows/help.md +++ b/get-shit-done/workflows/help.md @@ -276,6 +276,57 @@ Systematic debugging with persistent state across context resets. Usage: `/gsd-debug "login button doesn't work"` Usage: `/gsd-debug` (resume active session) +### Spiking & Sketching + +**`/gsd-spike [idea] [--quick]`** +Rapidly spike an idea with throwaway experiments to validate feasibility. + +- Decomposes idea into 2-5 focused experiments (risk-ordered) +- Each spike answers one specific Given/When/Then question +- Builds minimum code, runs it, captures verdict (VALIDATED/INVALIDATED/PARTIAL) +- Saves to `.planning/spikes/` with MANIFEST.md tracking +- Does not require `/gsd-new-project` — works in any repo +- `--quick` skips decomposition, builds immediately + +Usage: `/gsd-spike "can we stream LLM output over WebSockets?"` +Usage: `/gsd-spike --quick "test if pdfjs extracts tables"` + +**`/gsd-sketch [idea] [--quick]`** +Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration. + +- Conversational mood/direction intake before building +- Each sketch produces 2-3 variants as tabbed HTML pages +- User compares variants, cherry-picks elements, iterates +- Shared CSS theme system compounds across sketches +- Saves to `.planning/sketches/` with MANIFEST.md tracking +- Does not require `/gsd-new-project` — works in any repo +- `--quick` skips mood intake, jumps to building + +Usage: `/gsd-sketch "dashboard layout for the admin panel"` +Usage: `/gsd-sketch --quick "form card grouping"` + +**`/gsd-spike-wrap-up`** +Package spike findings into a persistent project skill. + +- Curates each spike one-at-a-time (include/exclude/partial/UAT) +- Groups findings by feature area +- Generates `./.claude/skills/spike-findings-[project]/` with references and sources +- Writes summary to `.planning/spikes/WRAP-UP-SUMMARY.md` +- Adds auto-load routing line to project CLAUDE.md + +Usage: `/gsd-spike-wrap-up` + +**`/gsd-sketch-wrap-up`** +Package sketch design findings into a persistent project skill. + +- Curates each sketch one-at-a-time (include/exclude/partial/revisit) +- Groups findings by design area +- Generates `./.claude/skills/sketch-findings-[project]/` with design decisions, CSS patterns, HTML structures +- Writes summary to `.planning/sketches/WRAP-UP-SUMMARY.md` +- Adds auto-load routing line to project CLAUDE.md + +Usage: `/gsd-sketch-wrap-up` + ### Quick Notes **`/gsd-note `** @@ -478,6 +529,13 @@ Usage: `/gsd-join-discord` ├── todos/ # Captured ideas and tasks │ ├── pending/ # Todos waiting to be worked on │ └── done/ # Completed todos +├── spikes/ # Spike experiments (/gsd-spike) +│ ├── MANIFEST.md # Spike inventory and verdicts +│ └── NNN-name/ # Individual spike directories +├── sketches/ # Design sketches (/gsd-sketch) +│ ├── MANIFEST.md # Sketch inventory and winners +│ ├── themes/ # Shared CSS theme files +│ └── NNN-name/ # Individual sketch directories (HTML + README) ├── debug/ # Active debug sessions │ └── resolved/ # Archived resolved issues ├── milestones/ diff --git a/get-shit-done/workflows/new-project.md b/get-shit-done/workflows/new-project.md index 8a598d508..b7aef797c 100644 --- a/get-shit-done/workflows/new-project.md +++ b/get-shit-done/workflows/new-project.md @@ -233,6 +233,36 @@ gsd-sdk query config-set workflow._auto_chain_active true Proceed to Step 4 (skip Steps 3 and 5). +## 2b. Prior Spike/Sketch Detection + +Check for existing spike and sketch work that should inform project setup: + +```bash +# Check for spike findings skill (project-local) +SPIKE_SKILL=$(ls ./.claude/skills/spike-findings-*/SKILL.md 2>/dev/null | head -1) + +# Check for sketch findings skill (project-local) +SKETCH_SKILL=$(ls ./.claude/skills/sketch-findings-*/SKILL.md 2>/dev/null | head -1) + +# Check for raw spikes/sketches in .planning/ +HAS_SPIKES=$(ls .planning/spikes/MANIFEST.md 2>/dev/null) +HAS_SKETCHES=$(ls .planning/sketches/MANIFEST.md 2>/dev/null) +``` + +If any of these exist, surface them before questioning: + +``` +⚡ Prior exploration detected: +{if SPIKE_SKILL} ✓ Spike findings skill: {path} — validated patterns from experiments +{if SKETCH_SKILL} ✓ Sketch findings skill: {path} — validated design decisions +{if HAS_SPIKES && !SPIKE_SKILL} ◆ Raw spikes in .planning/spikes/ — consider `/gsd-spike-wrap-up` to package findings +{if HAS_SKETCHES && !SKETCH_SKILL} ◆ Raw sketches in .planning/sketches/ — consider `/gsd-sketch-wrap-up` to package findings + +These findings will be incorporated into project context and available to planning agents. +``` + +If spike/sketch findings skills exist, read their SKILL.md files to inform the questioning phase — they contain validated patterns, constraints, and design decisions that should shape the project definition. + ## 3. Deep Questioning **If auto mode:** Skip (already handled in Step 2a). Extract project context from provided document instead and proceed to Step 4. diff --git a/get-shit-done/workflows/next.md b/get-shit-done/workflows/next.md index 7433f8919..026d5ba69 100644 --- a/get-shit-done/workflows/next.md +++ b/get-shit-done/workflows/next.md @@ -134,6 +134,29 @@ gsd-sdk query commit "docs: defer incomplete Phase {src} items to backlog" **If the user chooses "Force" (F):** Continue to `determine_next_action` without recording deferral. + +Check for pending spike/sketch work and surface a notice (does not change routing): + +```bash +# Check for pending spikes (verdict: PENDING in any README) +PENDING_SPIKES=$(grep -rl 'verdict: PENDING' .planning/spikes/*/README.md 2>/dev/null | wc -l | tr -d ' ') + +# Check for pending sketches (winner: null in any README) +PENDING_SKETCHES=$(grep -rl 'winner: null' .planning/sketches/*/README.md 2>/dev/null | wc -l | tr -d ' ') +``` + +If either count is > 0, display before routing: +``` +⚠ Pending exploratory work: + {PENDING_SPIKES} spike(s) with unresolved verdicts in .planning/spikes/ + {PENDING_SKETCHES} sketch(es) without a winning variant in .planning/sketches/ + + Resume with `/gsd-spike` or `/gsd-sketch`, or continue with phase work below. +``` + +Only show lines for non-zero counts. If both are 0, skip this notice entirely. + + Apply routing rules based on state: diff --git a/get-shit-done/workflows/pause-work.md b/get-shit-done/workflows/pause-work.md index 976c17f31..f4bb5c7d9 100644 --- a/get-shit-done/workflows/pause-work.md +++ b/get-shit-done/workflows/pause-work.md @@ -18,7 +18,10 @@ Determine what kind of work is being paused and set the handoff destination acco phase=$(( ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true ) | head -1 | grep -oP 'phases/\K[^/]+' || true) # Check for active spike -spike=$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md 2>/dev/null || true ) | head -1 | grep -oP 'spikes/\K[^/]+' || true) +spike=$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md .planning/spikes/*/README.md 2>/dev/null || true ) | head -1 | grep -oP 'spikes/\K[^/]+' || true) + +# Check for active sketch +sketch=$(( ls -lt .planning/sketches/*/README.md .planning/sketches/*/index.html 2>/dev/null || true ) | head -1 | grep -oP 'sketches/\K[^/]+' || true) # Check for active deliberation deliberation=$(ls .planning/deliberations/*.md 2>/dev/null | head -1 || true) @@ -26,8 +29,9 @@ deliberation=$(ls .planning/deliberations/*.md 2>/dev/null | head -1 || true) - **Phase work**: active phase directory → handoff to `.planning/phases/XX-name/.continue-here.md` - **Spike work**: active spike directory or spike-related files (no active phase) → handoff to `.planning/spikes/SPIKE-NNN/.continue-here.md` (create directory if needed) -- **Deliberation work**: active deliberation file (no phase/spike) → handoff to `.planning/deliberations/.continue-here.md` -- **Research work**: research notes exist but no phase/spike/deliberation → handoff to `.planning/.continue-here.md` +- **Sketch work**: active sketch directory (no active phase/spike) → handoff to `.planning/sketches/.continue-here.md` +- **Deliberation work**: active deliberation file (no phase/spike/sketch) → handoff to `.planning/deliberations/.continue-here.md` +- **Research work**: research notes exist but no phase/spike/sketch/deliberation → handoff to `.planning/.continue-here.md` - **Default**: no detectable context → handoff to `.planning/.continue-here.md`, note the ambiguity in `` If phase is detected, proceed with phase handoff path. Otherwise use the first matching non-phase path above. @@ -106,7 +110,7 @@ timestamp=$(gsd-sdk query current-timestamp full --raw) ```markdown --- -context: [phase|spike|deliberation|research|default] +context: [phase|spike|sketch|deliberation|research|default] phase: XX-name task: 3 total_tasks: 7 diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index cf7cbda32..741a5ea24 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -593,6 +593,10 @@ UAT_PATH=$(_gsd_field "$INIT" uat_path) CONTEXT_PATH=$(_gsd_field "$INIT" context_path) REVIEWS_PATH=$(_gsd_field "$INIT" reviews_path) PATTERNS_PATH=$(_gsd_field "$INIT" patterns_path) + +# Detect spike/sketch findings skills (project-local) +SPIKE_FINDINGS_PATH=$(ls ./.claude/skills/spike-findings-*/SKILL.md 2>/dev/null | head -1) +SKETCH_FINDINGS_PATH=$(ls ./.claude/skills/sketch-findings-*/SKILL.md 2>/dev/null | head -1) ``` ## 7.5. Verify Nyquist Artifacts @@ -706,6 +710,8 @@ Planner prompt: - {uat_path} (UAT Gaps - if --gaps) - {reviews_path} (Cross-AI Review Feedback - if --reviews) - {UI_SPEC_PATH} (UI Design Contract — visual/interaction specs, if exists) +- {SPIKE_FINDINGS_PATH} (Spike Findings — validated patterns, constraints, landmines from experiments, if exists) +- {SKETCH_FINDINGS_PATH} (Sketch Findings — validated design decisions, CSS patterns, visual direction, if exists) ${CONTEXT_WINDOW >= 500000 ? ` **Cross-phase context (1M model enrichment):** - CONTEXT.md files from the 3 most recent completed phases (locked decisions — maintain consistency) diff --git a/get-shit-done/workflows/sketch-wrap-up.md b/get-shit-done/workflows/sketch-wrap-up.md new file mode 100644 index 000000000..1f12b48a7 --- /dev/null +++ b/get-shit-done/workflows/sketch-wrap-up.md @@ -0,0 +1,283 @@ + +Curate sketch design findings and package them into a persistent project skill for future +UI implementation. Reads from `.planning/sketches/`, writes skill to `./.claude/skills/sketch-findings-[project]/` +(project-local) and summary to `.planning/sketches/WRAP-UP-SUMMARY.md`. +Companion to `/gsd-sketch`. + + + +Read all files referenced by the invoking prompt's execution_context before starting. + + + + + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► SKETCH WRAP-UP +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + + + +## Gather Sketch Inventory + +1. Read `.planning/sketches/MANIFEST.md` for the design direction and reference points +2. Glob `.planning/sketches/*/README.md` and parse YAML frontmatter from each +3. Check if `./.claude/skills/sketch-findings-*/SKILL.md` exists for this project + - If yes: read its `processed_sketches` list and filter those out + - If no: all sketches are candidates + +If no unprocessed sketches exist: +``` +No unprocessed sketches found in `.planning/sketches/`. +Run `/gsd-sketch` first to create design explorations. +``` +Exit. + +Check `commit_docs` config: +```bash +COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true") +``` + + + +## Curate Sketches One-at-a-Time + +Present each unprocessed sketch in ascending order. For each sketch, show: + +- **Sketch number and name** +- **Design question:** from frontmatter +- **Winner:** which variant was selected (if any) +- **Tags:** from frontmatter +- **Key decisions:** summarize what was decided visually + +Then ask the user: + +╔══════════════════════════════════════════════════════════════╗ +║ CHECKPOINT: Decision Required ║ +╚══════════════════════════════════════════════════════════════╝ + +Sketch {NNN}: {name} — Winner: Variant {X} + +{key design decisions summary} + +────────────────────────────────────────────────────────────── +→ Include / Exclude / Partial / Let me look at it +────────────────────────────────────────────────────────────── + +**If "Let me look at it":** +1. Provide: `open .planning/sketches/NNN-name/index.html` +2. Remind them which variant won and what to look for +3. After they've looked, return to the include/exclude/partial decision + +**If "Partial":** +Ask what specifically to include or exclude from this sketch's decisions. + + + +## Auto-Group by Design Area + +After all sketches are curated: + +1. Read all included sketches' tags, names, and content +2. Propose design-area groupings, e.g.: + - "**Layout & Navigation** — sketches 001, 004" + - "**Form Controls** — sketches 002, 005" + - "**Color & Typography** — sketches 003" +3. Present the grouping for approval — user may merge, split, rename, or rearrange + +Each group becomes one reference file in the generated skill. + + + +## Determine Output Skill Name + +Derive from the project directory name: `./.claude/skills/sketch-findings-[project-dir-name]/` + +If a skill already exists at that path (append mode), update in place. + + + +## Copy Source Files + +For each included sketch: + +1. Copy the winning variant's HTML file (or the full index.html with all variants) into `sources/NNN-sketch-name/` +2. Copy the winning theme.css into `sources/themes/` +3. Exclude node_modules, build artifacts, .DS_Store + + + +## Synthesize Reference Files + +For each design-area group, write a reference file at `references/[design-area-name].md`: + +```markdown +# [Design Area Name] + +## Design Decisions +[For each validated decision: what was chosen, why it won over alternatives, the key visual properties (colors, spacing, border radius, typography)] + +## CSS Patterns +[Key CSS snippets from winning variants — layout structures, component patterns, animation patterns. Extracted and cleaned up for reference.] + +## HTML Structures +[Key HTML patterns from winning variants — page layout, component markup, navigation structures.] + +## What to Avoid +[Design directions that were tried and rejected. Why they didn't work.] + +## Origin +Synthesized from sketches: NNN, NNN +Source files available in: sources/NNN-sketch-name/ +``` + + + +## Write SKILL.md + +Create (or update) the generated skill's SKILL.md: + +```markdown +--- +name: sketch-findings-[project-dir-name] +description: Validated design decisions, CSS patterns, and visual direction from sketch experiments. Auto-loaded during UI implementation on [project-dir-name]. +--- + + +## Project: [project-dir-name] + +[Design direction paragraph from MANIFEST.md] +[Reference points mentioned during intake] + +Sketch sessions wrapped: [date(s)] + + + +## Overall Direction + +[Summary of the validated visual direction: palette, typography, spacing system, layout approach, interaction patterns] + + + +## Design Areas + +| Area | Reference | Key Decision | +|------|-----------|--------------| +| [Name] | references/[name].md | [One-line summary] | + +## Theme + +The winning theme file is at `sources/themes/default.css`. + +## Source Files + +Original sketch HTML files are preserved in `sources/` for complete reference. + + + +## Processed Sketches + +[List of sketch numbers wrapped up] + +- 001-sketch-name +- 002-sketch-name + +``` + + + +## Write Planning Summary + +Write `.planning/sketches/WRAP-UP-SUMMARY.md` for project history: + +```markdown +# Sketch Wrap-Up Summary + +**Date:** [date] +**Sketches processed:** [count] +**Design areas:** [list] +**Skill output:** `./.claude/skills/sketch-findings-[project]/` + +## Included Sketches +| # | Name | Winner | Design Area | +|---|------|--------|-------------| + +## Excluded Sketches +| # | Name | Reason | +|---|------|--------| + +## Design Direction +[consolidated design direction summary] + +## Key Decisions +[layout, palette, typography, spacing, interaction patterns] +``` + + + +## Update Project CLAUDE.md + +Add an auto-load routing line: + +``` +- **Sketch findings for [project]** (design decisions, CSS patterns, visual direction) → `Skill("sketch-findings-[project-dir-name]")` +``` + +If this routing line already exists (append mode), leave it as-is. + + + +Commit all artifacts (if `COMMIT_DOCS` is true): + +```bash +gsd-sdk query commit "docs(sketch-wrap-up): package [N] sketch findings into project skill" .planning/sketches/WRAP-UP-SUMMARY.md +``` + + + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► SKETCH WRAP-UP COMPLETE ✓ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**Curated:** {N} sketches ({included} included, {excluded} excluded) +**Design areas:** {list} +**Skill:** `./.claude/skills/sketch-findings-[project]/` +**Summary:** `.planning/sketches/WRAP-UP-SUMMARY.md` +**CLAUDE.md:** routing line added + +The sketch-findings skill will auto-load when building the UI. +``` + +─────────────────────────────────────────────────────────────── + +## ▶ Next Up + +**Start building** — implement the validated design + +`/gsd-plan-phase` + +─────────────────────────────────────────────────────────────── + +**Also available:** +- `/gsd-ui-phase` — generate a UI design contract for a frontend phase +- `/gsd-sketch` — sketch additional design areas +- `/gsd-explore` — continue exploring + +─────────────────────────────────────────────────────────────── + + + + + +- [ ] Every unprocessed sketch presented for individual curation +- [ ] Design-area grouping proposed and approved +- [ ] Sketch-findings skill exists at `./.claude/skills/` with SKILL.md, references/, sources/ +- [ ] Winning theme.css copied into skill sources +- [ ] 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 + diff --git a/get-shit-done/workflows/sketch.md b/get-shit-done/workflows/sketch.md new file mode 100644 index 000000000..0a3d66419 --- /dev/null +++ b/get-shit-done/workflows/sketch.md @@ -0,0 +1,260 @@ + +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`. + + + +Read all files referenced by the invoking prompt's execution_context before starting. + +@~/.claude/get-shit-done/references/sketch-theme-system.md +@~/.claude/get-shit-done/references/sketch-variant-patterns.md +@~/.claude/get-shit-done/references/sketch-interactivity.md +@~/.claude/get-shit-done/references/sketch-tooling.md + + + + + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► SKETCHING +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +Parse `$ARGUMENTS` for: +- `--quick` flag → set `QUICK_MODE=true` +- Remaining text → the design idea to sketch + + + +Create `.planning/sketches/` and themes directory if they don't exist: + +```bash +mkdir -p .planning/sketches/themes +``` + +Check for existing sketches to determine numbering: +```bash +ls -d .planning/sketches/[0-9][0-9][0-9]-* 2>/dev/null | sort | tail -1 +``` + +Check `commit_docs` config: +```bash +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`. + +**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. + +**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) + +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. + +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. + + + +Break the idea into 2-5 design questions. Present as a table: + +| Sketch | Design question | Approach | Risk | +|--------|----------------|----------|------| +| 001 | Does a two-panel layout feel right? | Sidebar + main, variants: fixed/collapsible/floating | **High** — sets page structure | +| 002 | How should the form controls look? | Grouped cards, variants: stacked/inline/floating labels | Medium | + +Each sketch answers one specific visual question. Good sketches: +- "Does this layout feel right?" — build with real-ish content +- "How should these controls be grouped?" — build with actual labels and inputs +- "What does this interaction feel like?" — build the hover/click/transition +- "Does this color palette work?" — apply to actual UI, not a swatch grid + +Bad sketches: +- "Design the whole app" — too broad +- "Set up the component library" — that's implementation +- "Pick a color palette" — apply it to UI instead + +Present the table and get alignment before building. + + + +Create or update `.planning/sketches/MANIFEST.md`: + +```markdown +# Sketch Manifest + +## Design Direction +[One paragraph capturing the mood/feel/direction from the intake conversation] + +## Reference Points +[Apps/sites the user referenced] + +## Sketches + +| # | Name | Design Question | Winner | Tags | +|---|------|----------------|--------|------| +``` + +If MANIFEST.md already exists, append new sketches to the existing table. + + + +If no theme exists yet at `.planning/sketches/themes/default.css`, create one based on the mood/direction from the intake step. See `sketch-theme-system.md` for the full template. + +Adapt colors, fonts, spacing, and shapes to match the agreed aesthetic — don't use the defaults verbatim unless they match the mood. + + + +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. + +**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. + +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 +- 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. + +**d.** Write `README.md`: + +```markdown +--- +sketch: NNN +name: descriptive-name +question: "What layout structure feels right for the dashboard?" +winner: null +tags: [layout, dashboard] +--- + +# Sketch NNN: Descriptive Name + +## Design Question +[The specific visual question this sketch answers] + +## How to View +open .planning/sketches/NNN-descriptive-name/index.html + +## Variants +- **A: [name]** — [one-line description of this approach] +- **B: [name]** — [one-line description] +- **C: [name]** — [one-line description] + +## What to Look For +[Specific things to pay attention to when comparing variants] +``` + +**e.** Present to the user with a checkpoint: + +╔══════════════════════════════════════════════════════════════╗ +║ CHECKPOINT: Verification Required ║ +╚══════════════════════════════════════════════════════════════╝ + +**Sketch {NNN}: {name}** + +Open: `open .planning/sketches/NNN-name/index.html` + +Compare: {what to look for between variants} + +────────────────────────────────────────────────────────────── +→ Which variant feels right? Or cherry-pick elements across 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 + +Iterate until the user is satisfied with a direction for this sketch. + +**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 + +**h.** Commit (if `COMMIT_DOCS` is true): +```bash +gsd-sdk query commit "docs(sketch-NNN): [winning direction] — [key visual insight]" .planning/sketches/NNN-descriptive-name/ .planning/sketches/MANIFEST.md +``` + +**i.** Report: +``` +◆ Sketch NNN: {name} + Winner: Variant {X} — {description} + Insight: {key visual decision made} +``` + + + +After all sketches complete, present the summary: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► SKETCH COMPLETE ✓ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## Design Direction +{what we landed on overall} + +## Key Decisions +{layout, palette, typography, spacing, interaction patterns} + +## Open Questions +{anything unresolved or worth revisiting} +``` + +─────────────────────────────────────────────────────────────── + +## ▶ Next Up + +**Package findings** — wrap design decisions into a reusable skill + +`/gsd-sketch-wrap-up` + +─────────────────────────────────────────────────────────────── + +**Also available:** +- `/gsd-plan-phase` — start building the real UI +- `/gsd-explore` — continue exploring the concept +- `/gsd-spike` — spike technical feasibility of a design pattern + +─────────────────────────────────────────────────────────────── + + + + + +- [ ] `.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 +- [ ] 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) +- [ ] MANIFEST.md is current +- [ ] Commits use `docs(sketch-NNN): [winner]` format +- [ ] Summary presented with next-step routing + diff --git a/get-shit-done/workflows/spike-wrap-up.md b/get-shit-done/workflows/spike-wrap-up.md new file mode 100644 index 000000000..ce543cc39 --- /dev/null +++ b/get-shit-done/workflows/spike-wrap-up.md @@ -0,0 +1,273 @@ + +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`. + + + +Read all files referenced by the invoking prompt's execution_context before starting. + + + + + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► SPIKE WRAP-UP +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + + + +## Gather Spike Inventory + +1. Read `.planning/spikes/MANIFEST.md` for the overall idea context +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 + - If no: all spikes are candidates + +If no unprocessed spikes exist: +``` +No unprocessed spikes found in `.planning/spikes/`. +Run `/gsd-spike` first to create experiments. +``` +Exit. + +Check `commit_docs` config: +```bash +COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true") +``` + + + +## Curate Spikes One-at-a-Time + +Present each unprocessed spike in ascending order. For each spike, show: + +- **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 + +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. + + + +## 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 + +Each group becomes one reference file in the generated skill. + + + +## Determine Output Skill Name + +Derive the skill name from the project directory: + +1. Get the project root directory name (e.g., `solana-tracker`) +2. The skill will be created at `./.claude/skills/spike-findings-[project-dir-name]/` + +If a skill already exists at that path (append mode), update in place. + + + +## Copy Source Files + +For each included spike: + +1. Identify the core source files — the actual scripts, main files, and config that make the spike work. Exclude: + - `node_modules/`, `__pycache__/`, `.venv/`, build artifacts + - Lock files (`package-lock.json`, `yarn.lock`, etc.) + - `.git/`, `.DS_Store` +2. Copy the README.md and core source files into `sources/NNN-spike-name/` inside the generated skill directory + + + +## Synthesize Reference Files + +For each feature-area group, write a reference file at `references/[feature-area-name].md`: + +```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] + +## Landmines +[Things that look right but aren't. Gotchas. Anti-patterns discovered during spiking.] + +## 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/ +``` + + + +## Write SKILL.md + +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]. +--- + + +## Project: [project-dir-name] + +[One paragraph from MANIFEST.md describing the overall idea] + +Spike sessions wrapped: [date(s)] + + + +## Feature Areas + +| Area | Reference | Key Finding | +|------|-----------|-------------| +| [Name] | references/[name].md | [One-line summary] | + +## Source Files + +Original spike source files are preserved in `sources/` for complete reference. + + + +## Processed Spikes + +[List of spike numbers wrapped up] + +- 001-spike-name +- 002-spike-name + +``` + + + +## Write Planning Summary + +Write `.planning/spikes/WRAP-UP-SUMMARY.md` for project history: + +```markdown +# Spike Wrap-Up Summary + +**Date:** [date] +**Spikes processed:** [count] +**Feature areas:** [list] +**Skill output:** `./.claude/skills/spike-findings-[project]/` + +## Included Spikes +| # | Name | Verdict | Feature Area | +|---|------|---------|--------------| + +## Excluded Spikes +| # | Name | Reason | +|---|------|--------| + +## Key Findings +[consolidated findings summary] +``` + + + +## Update Project CLAUDE.md + +Add an auto-load routing line to the project's CLAUDE.md (create the file if it doesn't exist): + +``` +- **Spike findings for [project]** (implementation patterns, constraints, gotchas) → `Skill("spike-findings-[project-dir-name]")` +``` + +If this routing line already exists (append mode), leave it as-is. + + + +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 ► SPIKE WRAP-UP COMPLETE ✓ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**Curated:** {N} spikes ({included} included, {excluded} excluded) +**Feature areas:** {list} +**Skill:** `./.claude/skills/spike-findings-[project]/` +**Summary:** `.planning/spikes/WRAP-UP-SUMMARY.md` +**CLAUDE.md:** routing line added + +The spike-findings skill will auto-load in future build conversations. +``` + +─────────────────────────────────────────────────────────────── + +## ▶ Next Up + +**Start building** — plan the real implementation + +`/gsd-plan-phase` + +─────────────────────────────────────────────────────────────── + +**Also available:** +- `/gsd-add-phase` — add a phase based on spike findings +- `/gsd-spike` — spike additional ideas +- `/gsd-explore` — continue exploring + +─────────────────────────────────────────────────────────────── + + + + + +- [ ] 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 +- [ ] `.planning/spikes/WRAP-UP-SUMMARY.md` written for project history +- [ ] Project CLAUDE.md has auto-load routing line +- [ ] Summary presented with next-step routing + diff --git a/get-shit-done/workflows/spike.md b/get-shit-done/workflows/spike.md new file mode 100644 index 000000000..f2db5752f --- /dev/null +++ b/get-shit-done/workflows/spike.md @@ -0,0 +1,270 @@ + +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`. + + + +Read all files referenced by the invoking prompt's execution_context before starting. + + + + + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► SPIKING +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +Parse `$ARGUMENTS` for: +- `--quick` flag → set `QUICK_MODE=true` +- Remaining text → the idea to spike + + + +Create `.planning/spikes/` if it doesn't exist: + +```bash +mkdir -p .planning/spikes +``` + +Check for existing spikes to determine numbering: +```bash +ls -d .planning/spikes/[0-9][0-9][0-9]-* 2>/dev/null | sort | tail -1 +``` + +Check `commit_docs` config: +```bash +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: + +```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). + +Avoid unless the spike specifically requires it: +- Complex package management beyond `npm install` or `pip install` +- Build tools, bundlers, or transpilers +- Docker, containers, or infrastructure +- Env files or config systems — hardcode everything + + + +**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`. + +**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: + +``` +| # | 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 | +``` + +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 + +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 + +Order by risk — the spike 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 ║ +╚══════════════════════════════════════════════════════════════╝ + +{spike table from decompose step} + +────────────────────────────────────────────────────────────── +→ Build all in this order, or adjust the list? +────────────────────────────────────────────────────────────── + +The user may reorder, merge, split, or skip spikes. Wait for alignment. + + + +Create or update `.planning/spikes/MANIFEST.md`: + +```markdown +# Spike Manifest + +## Idea +[One paragraph describing the overall idea being explored] + +## Spikes + +| # | Name | Validates | Verdict | Tags | +|---|------|-----------|---------|------| +``` + +If MANIFEST.md already exists, append new spikes to the existing table. + + + +Build each spike sequentially, highest-risk first. + +### For Each Spike: + +**a.** Find next available number by checking existing `.planning/spikes/NNN-*/` directories. +Format: three-digit zero-padded + hyphenated descriptive name. + +**b.** Create the spike directory: `.planning/spikes/NNN-descriptive-name/` + +**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?" + +**d.** Write `README.md` with YAML frontmatter: + +```markdown +--- +spike: NNN +name: descriptive-name +validates: "Given [precondition], when [action], then [expected outcome]" +verdict: PENDING +related: [] +tags: [tag1, tag2] +--- + +# Spike NNN: Descriptive Name + +## What This Validates +[The specific feasibility question, framed as Given/When/Then] + +## How to Run +[Single command or short sequence to run the spike] + +## What to Expect +[Concrete observable outcomes: "When you click X, you should see Y within Z seconds"] + +## Results +[Filled in after running — verdict, evidence, surprises] +``` + +**e.** Auto-link related spikes: read existing spike READMEs and infer relationships from tags, names, and descriptions. Write the `related` field 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: + +╔══════════════════════════════════════════════════════════════╗ +║ CHECKPOINT: Verification Required ║ +╚══════════════════════════════════════════════════════════════╝ + +**Spike {NNN}: {name}** + +**How to run:** {command} +**What to expect:** {concrete outcomes} + +────────────────────────────────────────────────────────────── +→ 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 +``` + +**j.** Report before moving to next spike: +``` +◆ Spike NNN: {name} + Verdict: {VALIDATED ✓ / INVALIDATED ✗ / PARTIAL ⚠} + Finding: {one sentence} + Impact: {effect on remaining spikes, if any} +``` + +**k.** If a spike invalidates a core assumption: stop and present: + +╔══════════════════════════════════════════════════════════════╗ +║ 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. + + + +After all spikes complete, present the consolidated report: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► SPIKE COMPLETE ✓ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +## Verdicts + +| # | Name | Verdict | +|---|------|---------| +| 001 | {name} | ✓ VALIDATED | +| 002 | {name} | ✗ INVALIDATED | + +## Key Discoveries +{surprises, gotchas, things that weren't expected} + +## Feasibility Assessment +{overall, is the idea viable?} + +## Signal for the Build +{what the real implementation should use, avoid, or watch out for} +``` + +─────────────────────────────────────────────────────────────── + +## ▶ Next Up + +**Package findings** — wrap spike knowledge into a reusable skill + +`/gsd-spike-wrap-up` + +─────────────────────────────────────────────────────────────── + +**Also available:** +- `/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 + +─────────────────────────────────────────────────────────────── + + + + + +- [ ] `.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 +- [ ] Commits use `docs(spike-NNN): [VERDICT]` format +- [ ] Consolidated report presented with next-step routing +- [ ] If core assumption invalidated, execution stopped and user consulted +