feat: add /gsd-spike, /gsd-sketch, /gsd-spike-wrap-up, /gsd-sketch-wrap-up commands
First-class GSD commands for rapid feasibility spiking and UI design sketching, ported from personal skills into the framework with full GSD integration: - Spikes save to .planning/spikes/, sketches to .planning/sketches/ - GSD banners, checkpoint boxes, Next Up blocks, gsd-sdk query commits - --quick flag skips intake/decomposition for both commands - Wrap-up commands package findings into project-local .claude/skills/ and write WRAP-UP-SUMMARY.md to .planning/ for project history - Neither requires /gsd-new-project — auto-creates .planning/ subdirs Pipeline integration: - new-project.md detects prior spike/sketch work on init - discuss-phase.md loads spike/sketch findings into prior context - plan-phase.md includes findings in planner <files_to_read> - do.md routes spike/sketch intent to new commands - explore.md offers spike/sketch as output routes - next.md surfaces pending spike/sketch work as notices - pause-work.md detects active sketch context for handoff - help.md documents all 4 commands with usage examples - artifact-types.md registers spike/sketch artifact taxonomy Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
31
commands/gsd/sketch-wrap-up.md
Normal file
31
commands/gsd/sketch-wrap-up.md
Normal file
@@ -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
|
||||
---
|
||||
<objective>
|
||||
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).
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/sketch-wrap-up.md
|
||||
@~/.claude/get-shit-done/references/ui-brand.md
|
||||
</execution_context>
|
||||
|
||||
<runtime_note>
|
||||
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
|
||||
</runtime_note>
|
||||
|
||||
<process>
|
||||
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).
|
||||
</process>
|
||||
45
commands/gsd/sketch.md
Normal file
45
commands/gsd/sketch.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: gsd:sketch
|
||||
description: Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration
|
||||
argument-hint: "<design idea to explore> [--quick]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
- AskUserQuestion
|
||||
---
|
||||
<objective>
|
||||
Explore design directions through throwaway HTML mockups before committing to implementation.
|
||||
Each sketch produces 2-3 variants for comparison. Sketches live in `.planning/sketches/` and
|
||||
integrate with GSD commit patterns, state tracking, and handoff workflows.
|
||||
|
||||
Does not require `/gsd-new-project` — auto-creates `.planning/sketches/` if needed.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.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
|
||||
</execution_context>
|
||||
|
||||
<runtime_note>
|
||||
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
|
||||
</runtime_note>
|
||||
|
||||
<context>
|
||||
Design idea: $ARGUMENTS
|
||||
|
||||
**Available flags:**
|
||||
- `--quick` — Skip mood/direction intake, jump straight to decomposition and building. Use when the design direction is already clear.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
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).
|
||||
</process>
|
||||
31
commands/gsd/spike-wrap-up.md
Normal file
31
commands/gsd/spike-wrap-up.md
Normal file
@@ -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
|
||||
---
|
||||
<objective>
|
||||
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).
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/spike-wrap-up.md
|
||||
@~/.claude/get-shit-done/references/ui-brand.md
|
||||
</execution_context>
|
||||
|
||||
<runtime_note>
|
||||
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
|
||||
</runtime_note>
|
||||
|
||||
<process>
|
||||
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).
|
||||
</process>
|
||||
41
commands/gsd/spike.md
Normal file
41
commands/gsd/spike.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
name: gsd:spike
|
||||
description: Rapidly spike an idea with throwaway experiments to validate feasibility before planning
|
||||
argument-hint: "<idea to validate> [--quick]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
- AskUserQuestion
|
||||
---
|
||||
<objective>
|
||||
Rapid feasibility validation through focused, throwaway experiments. Each spike answers one
|
||||
specific question with observable evidence. Spikes live in `.planning/spikes/` and integrate
|
||||
with GSD commit patterns, state tracking, and handoff workflows.
|
||||
|
||||
Does not require `/gsd-new-project` — auto-creates `.planning/spikes/` if needed.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/spike.md
|
||||
@~/.claude/get-shit-done/references/ui-brand.md
|
||||
</execution_context>
|
||||
|
||||
<runtime_note>
|
||||
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
|
||||
</runtime_note>
|
||||
|
||||
<context>
|
||||
Idea: $ARGUMENTS
|
||||
|
||||
**Available flags:**
|
||||
- `--quick` — Skip decomposition/alignment, jump straight to building. Use when you already know what to spike.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
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).
|
||||
</process>
|
||||
@@ -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
|
||||
|
||||
41
get-shit-done/references/sketch-interactivity.md
Normal file
41
get-shit-done/references/sketch-interactivity.md
Normal file
@@ -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 `<script>` tags. No frameworks, no build step. Keep it simple:
|
||||
|
||||
```html
|
||||
<script>
|
||||
// Toggle a panel
|
||||
document.querySelector('.panel-toggle').addEventListener('click', (e) => {
|
||||
e.target.closest('.panel').classList.toggle('collapsed');
|
||||
});
|
||||
</script>
|
||||
```
|
||||
94
get-shit-done/references/sketch-theme-system.md
Normal file
94
get-shit-done/references/sketch-theme-system.md
Normal file
@@ -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
|
||||
<link rel="stylesheet" href="../themes/default.css">
|
||||
```
|
||||
|
||||
## 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
|
||||
<select id="theme-switcher" onchange="document.querySelector('link[href*=themes]').href='../themes/'+this.value+'.css'">
|
||||
<option value="default">Default</option>
|
||||
</select>
|
||||
```
|
||||
|
||||
Dynamically populate options by listing available theme files, or hardcode the known themes.
|
||||
45
get-shit-done/references/sketch-tooling.md
Normal file
45
get-shit-done/references/sketch-tooling.md
Normal file
@@ -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 `<div>` fixed to the bottom-right, semi-transparent, expands on hover:
|
||||
|
||||
```html
|
||||
<div id="sketch-tools" style="position:fixed;bottom:12px;right:12px;z-index:9999;font-family:system-ui;font-size:12px;background:rgba(0,0,0,0.7);color:white;padding:8px 12px;border-radius:8px;opacity:0.4;transition:opacity 0.2s;" onmouseenter="this.style.opacity='1'" onmouseleave="this.style.opacity='0.4'">
|
||||
<!-- Theme switcher -->
|
||||
<!-- Viewport buttons -->
|
||||
<!-- Annotation toggle -->
|
||||
</div>
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### Theme Switcher
|
||||
|
||||
A dropdown that swaps the theme CSS file at runtime:
|
||||
|
||||
```html
|
||||
<select onchange="document.querySelector('link[href*=themes]').href='../themes/'+this.value+'.css'">
|
||||
<option value="default">Default</option>
|
||||
</select>
|
||||
```
|
||||
|
||||
### 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).
|
||||
81
get-shit-done/references/sketch-variant-patterns.md
Normal file
81
get-shit-done/references/sketch-variant-patterns.md
Normal file
@@ -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
|
||||
<div id="variant-nav" style="position:fixed;top:0;left:0;right:0;z-index:9998;background:var(--color-surface, #fff);border-bottom:1px solid var(--color-border, #e5e5e5);padding:8px 16px;display:flex;gap:8px;font-family:system-ui;">
|
||||
<button class="variant-tab active" onclick="showVariant('a')">A: Sidebar Layout</button>
|
||||
<button class="variant-tab" onclick="showVariant('b')">B: Top Nav</button>
|
||||
<button class="variant-tab" onclick="showVariant('c')">C: Floating Panels</button>
|
||||
</div>
|
||||
|
||||
<div id="variant-a" class="variant active">
|
||||
<!-- Variant A content -->
|
||||
</div>
|
||||
<div id="variant-b" class="variant" style="display:none">
|
||||
<!-- Variant B content -->
|
||||
</div>
|
||||
<div id="variant-c" class="variant" style="display:none">
|
||||
<!-- Variant C content -->
|
||||
</div>
|
||||
|
||||
<script>
|
||||
function showVariant(id) {
|
||||
document.querySelectorAll('.variant').forEach(v => v.style.display = 'none');
|
||||
document.querySelectorAll('.variant-tab').forEach(t => t.classList.remove('active'));
|
||||
document.getElementById('variant-' + id).style.display = 'block';
|
||||
event.target.classList.add('active');
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
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
|
||||
<button class="variant-tab active">A: Sidebar Layout ★ Selected</button>
|
||||
```
|
||||
|
||||
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
|
||||
<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:24px;padding:24px;">
|
||||
<div>
|
||||
<h3>A: Rounded</h3>
|
||||
<!-- variant content -->
|
||||
</div>
|
||||
<div>
|
||||
<h3>B: Sharp</h3>
|
||||
<!-- variant content -->
|
||||
</div>
|
||||
<div>
|
||||
<h3>C: Pill</h3>
|
||||
<!-- variant content -->
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## 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
|
||||
<button class="variant-tab" onclick="showVariant('synth1')">Synthesis: A's layout + C's palette</button>
|
||||
```
|
||||
@@ -348,9 +348,40 @@ Structure the extracted information:
|
||||
</prior_decisions>
|
||||
```
|
||||
|
||||
**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 `<prior_decisions>`:
|
||||
```
|
||||
## 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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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:
|
||||
```
|
||||
|
||||
@@ -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 <text>`**
|
||||
@@ -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/
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
</step>
|
||||
|
||||
<step name="spike_sketch_notice">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="determine_next_action">
|
||||
Apply routing rules based on state:
|
||||
|
||||
|
||||
@@ -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 `<current_state>`
|
||||
|
||||
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
|
||||
|
||||
@@ -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)
|
||||
|
||||
283
get-shit-done/workflows/sketch-wrap-up.md
Normal file
283
get-shit-done/workflows/sketch-wrap-up.md
Normal file
@@ -0,0 +1,283 @@
|
||||
<purpose>
|
||||
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`.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="banner">
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► SKETCH WRAP-UP
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="gather">
|
||||
## 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")
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="curate">
|
||||
## 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.
|
||||
</step>
|
||||
|
||||
<step name="group">
|
||||
## 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.
|
||||
</step>
|
||||
|
||||
<step name="skill_name">
|
||||
## 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.
|
||||
</step>
|
||||
|
||||
<step name="copy_sources">
|
||||
## 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
|
||||
</step>
|
||||
|
||||
<step name="synthesize">
|
||||
## 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/
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="write_skill">
|
||||
## 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].
|
||||
---
|
||||
|
||||
<context>
|
||||
## Project: [project-dir-name]
|
||||
|
||||
[Design direction paragraph from MANIFEST.md]
|
||||
[Reference points mentioned during intake]
|
||||
|
||||
Sketch sessions wrapped: [date(s)]
|
||||
</context>
|
||||
|
||||
<design_direction>
|
||||
## Overall Direction
|
||||
|
||||
[Summary of the validated visual direction: palette, typography, spacing system, layout approach, interaction patterns]
|
||||
</design_direction>
|
||||
|
||||
<findings_index>
|
||||
## 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.
|
||||
</findings_index>
|
||||
|
||||
<metadata>
|
||||
## Processed Sketches
|
||||
|
||||
[List of sketch numbers wrapped up]
|
||||
|
||||
- 001-sketch-name
|
||||
- 002-sketch-name
|
||||
</metadata>
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="write_summary">
|
||||
## 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]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="update_claude_md">
|
||||
## 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.
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
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
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
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
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] 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
|
||||
</success_criteria>
|
||||
260
get-shit-done/workflows/sketch.md
Normal file
260
get-shit-done/workflows/sketch.md
Normal file
@@ -0,0 +1,260 @@
|
||||
<purpose>
|
||||
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`.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
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
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="banner">
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► SKETCHING
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Parse `$ARGUMENTS` for:
|
||||
- `--quick` flag → set `QUICK_MODE=true`
|
||||
- Remaining text → the design idea to sketch
|
||||
</step>
|
||||
|
||||
<step name="setup_directory">
|
||||
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")
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="mood_intake">
|
||||
**If `QUICK_MODE` is true:** Skip mood intake. Use whatever the user provided in `$ARGUMENTS` as the design direction. Jump to `decompose`.
|
||||
|
||||
**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.
|
||||
</step>
|
||||
|
||||
<step name="decompose">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="create_manifest">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="create_theme">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="build_sketches">
|
||||
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}
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
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
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] `.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
|
||||
</success_criteria>
|
||||
273
get-shit-done/workflows/spike-wrap-up.md
Normal file
273
get-shit-done/workflows/spike-wrap-up.md
Normal file
@@ -0,0 +1,273 @@
|
||||
<purpose>
|
||||
Curate spike experiment findings and package them into a persistent project skill for future
|
||||
build conversations. Reads from `.planning/spikes/`, writes skill to `./.claude/skills/spike-findings-[project]/`
|
||||
(project-local) and summary to `.planning/spikes/WRAP-UP-SUMMARY.md`.
|
||||
Companion to `/gsd-spike`.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="banner">
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► SPIKE WRAP-UP
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="gather">
|
||||
## 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")
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="curate">
|
||||
## 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.
|
||||
</step>
|
||||
|
||||
<step name="group">
|
||||
## 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.
|
||||
</step>
|
||||
|
||||
<step name="skill_name">
|
||||
## 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.
|
||||
</step>
|
||||
|
||||
<step name="copy_sources">
|
||||
## 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
|
||||
</step>
|
||||
|
||||
<step name="synthesize">
|
||||
## 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/
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="write_skill">
|
||||
## 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].
|
||||
---
|
||||
|
||||
<context>
|
||||
## Project: [project-dir-name]
|
||||
|
||||
[One paragraph from MANIFEST.md describing the overall idea]
|
||||
|
||||
Spike sessions wrapped: [date(s)]
|
||||
</context>
|
||||
|
||||
<findings_index>
|
||||
## 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.
|
||||
</findings_index>
|
||||
|
||||
<metadata>
|
||||
## Processed Spikes
|
||||
|
||||
[List of spike numbers wrapped up]
|
||||
|
||||
- 001-spike-name
|
||||
- 002-spike-name
|
||||
</metadata>
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="write_summary">
|
||||
## 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]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="update_claude_md">
|
||||
## 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.
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
Commit all artifacts (if `COMMIT_DOCS` is true):
|
||||
|
||||
```bash
|
||||
gsd-sdk query commit "docs(spike-wrap-up): package [N] spike findings into project skill" .planning/spikes/WRAP-UP-SUMMARY.md
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
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
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] 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
|
||||
</success_criteria>
|
||||
270
get-shit-done/workflows/spike.md
Normal file
270
get-shit-done/workflows/spike.md
Normal file
@@ -0,0 +1,270 @@
|
||||
<purpose>
|
||||
Rapid feasibility validation through focused, throwaway experiments. Each spike answers one
|
||||
specific question with observable evidence. Saves artifacts to `.planning/spikes/`.
|
||||
Companion to `/gsd-spike-wrap-up`.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="banner">
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► SPIKING
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Parse `$ARGUMENTS` for:
|
||||
- `--quick` flag → set `QUICK_MODE=true`
|
||||
- Remaining text → the idea to spike
|
||||
</step>
|
||||
|
||||
<step name="setup_directory">
|
||||
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")
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="detect_stack">
|
||||
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
|
||||
</step>
|
||||
|
||||
<step name="decompose">
|
||||
**If `QUICK_MODE` is true:** Skip decomposition and alignment. Take the user's idea as a single spike question. Assign it spike number `001` (or next available). Jump to `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.
|
||||
</step>
|
||||
|
||||
<step name="align">
|
||||
**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.
|
||||
</step>
|
||||
|
||||
<step name="create_manifest">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="build_spikes">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
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
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] `.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
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user