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:
@@ -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