8f2ebbe9bf
* feat(#1928): remove sunset gemini cli runtime, redirect to antigravity Google sunset Gemini CLI on 2026-06-18; Antigravity CLI is its official successor (already a first-class GSD runtime). Remove the gemini runtime from the enum (16->15), aliases, labels, config-home fragment, install path, converters (convertClaudeToGemini{Markdown,Toml,Agent}, convertSlashCommandsToGeminiMentions), capability descriptor, gemini-extension.json, RULESET.GEMINI.*, and the interactive menu (renumbered, no gap). --gemini now prints an explicit deprecation notice citing the 2026-06-18 sunset and redirects to --antigravity (no silent alias, per the issue's Hyrum's-Law rejection). Antigravity is preserved throughout: its GEMINI.md contextFileName, .gemini/antigravity config home, the shared convertGeminiToolName/claudeToGeminiTools tool vocabulary, and the 'gemini' hookEvents dialect it declares. GEMINI.md retargeted as Antigravity's context file. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(#1928): backfill changeset PR number (#1996) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(#1928): drop Gemini CLI from issue templates (review nit) Removes the sunset Gemini CLI runtime from the two GitHub issue-template runtime lists that the removal PR missed, per @davesienkowski's review nit: - feature_request.yml: 'Applicable runtimes' checkbox (a user could otherwise request a feature for a runtime GSD no longer supports) - bug_report.yml: 'Runtime' dropdown + the stale ~/.gemini/settings.json retrieval-help line Leaves the post-removal templates fully consistent with the Antigravity redirect. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
161 lines
5.7 KiB
Markdown
161 lines
5.7 KiB
Markdown
# How to spike and sketch before committing
|
||
|
||
**Goal:** De-risk an implementation by running focused feasibility experiments (spikes) and exploring visual directions through throwaway HTML mockups (sketches) before committing a phase to any specific approach.
|
||
|
||
**Prerequisites:** None. `/gsd-spike` and `/gsd-sketch` create their own storage directories and do not require an initialised GSD project.
|
||
|
||
---
|
||
|
||
## Decide: spike, sketch, or both
|
||
|
||
| You want to answer… | Use |
|
||
|---|---|
|
||
| "Will this technical approach actually work?" | `/gsd-spike` |
|
||
| "Does this layout / interaction / visual treatment feel right?" | `/gsd-sketch` |
|
||
| "What's the right technical approach, and what should it look like?" | Both, in order: spike first, then sketch |
|
||
|
||
Spikes answer binary feasibility questions with executable code and a VALIDATED / INVALIDATED / PARTIAL verdict. Sketches answer visual questions with 2–3 browser-comparable HTML variants. They are complementary — a spike proves the approach is buildable, a sketch proves the design is worth building.
|
||
|
||
---
|
||
|
||
## Run a spike
|
||
|
||
### Interactive intake (default)
|
||
|
||
```bash
|
||
/gsd-spike
|
||
```
|
||
|
||
GSD asks about the technical question, decomposes it into 2–5 independent experiments framed as **Given / When / Then** hypotheses, and asks for confirmation before building.
|
||
|
||
### Provide the idea directly
|
||
|
||
```bash
|
||
/gsd-spike "can we stream LLM tokens through SSE"
|
||
```
|
||
|
||
### Skip intake and run immediately
|
||
|
||
```bash
|
||
/gsd-spike --quick "websocket vs SSE latency"
|
||
```
|
||
|
||
`--quick` skips the decomposition conversation and treats the argument as a single spike question. Use this when the question is already specific enough to run without refinement.
|
||
|
||
### What each experiment produces
|
||
|
||
Each spike in `.planning/spikes/NNN-descriptive-name/` includes:
|
||
|
||
- Working code (not pseudocode)
|
||
- A **Given / When / Then** hypothesis written before any code
|
||
- An investigation trail documenting edge cases, pivots, and surprises
|
||
- A **VALIDATED**, **INVALIDATED**, or **PARTIAL** verdict with evidence
|
||
- A `README.md` with frontmatter, how-to-run instructions, and results
|
||
|
||
All spikes are indexed in `.planning/spikes/MANIFEST.md`.
|
||
|
||
### Package the findings
|
||
|
||
When you have signal, wrap the findings into a project-local skill so future sessions load them automatically:
|
||
|
||
```bash
|
||
/gsd-spike --wrap-up
|
||
```
|
||
|
||
This writes `.claude/skills/spike-findings-[project]/`. The skill is discovered automatically and loaded by subsequent `/gsd-sketch`, `/gsd-ui-phase`, and `/gsd-plan-phase` runs — you do not need to reference it explicitly.
|
||
|
||
---
|
||
|
||
## Run a sketch
|
||
|
||
### Mood intake (default)
|
||
|
||
```bash
|
||
/gsd-sketch
|
||
```
|
||
|
||
GSD opens a short conversation to explore feel, visual references, and the core user action before any code is written. It asks one question at a time and only starts building when you say go.
|
||
|
||
### Provide a design direction directly
|
||
|
||
```bash
|
||
/gsd-sketch "dashboard layout"
|
||
```
|
||
|
||
### Skip mood intake and run immediately
|
||
|
||
```bash
|
||
/gsd-sketch --quick "sidebar navigation"
|
||
```
|
||
|
||
`--quick` skips the intake conversation entirely and uses the argument as the design direction.
|
||
|
||
### Non-Claude runtimes (Codex, Antigravity CLI, etc.)
|
||
|
||
```bash
|
||
/gsd-sketch --text "onboarding flow"
|
||
```
|
||
|
||
`--text` replaces interactive prompts with plain-text numbered lists. Use this when your runtime does not support `AskUserQuestion`.
|
||
|
||
### What each sketch produces
|
||
|
||
Each sketch in `.planning/sketches/NNN-descriptive-name/` includes:
|
||
|
||
- `index.html` with 2–3 variants accessible via tab navigation — open directly in a browser, no build step
|
||
- Functional interactive elements (hover, click, transitions)
|
||
- Real-ish content using field names and data shapes from any prior spike findings
|
||
- Shared CSS variables from `.planning/sketches/themes/default.css`
|
||
- A `README.md` with the design question, variants, and what to look for
|
||
|
||
All sketches are indexed in `.planning/sketches/MANIFEST.md`.
|
||
|
||
### Package the winning design decisions
|
||
|
||
After picking a variant, capture the visual decisions into a project-local skill:
|
||
|
||
```bash
|
||
/gsd-sketch --wrap-up
|
||
```
|
||
|
||
This writes `.claude/skills/sketch-findings-[project]/`. The skill is picked up automatically by `/gsd-ui-phase` — pre-validated decisions (layout, colour palette, typography, spacing) are treated as locked and are not re-asked.
|
||
|
||
---
|
||
|
||
## Combined flow: spike → sketch → phase
|
||
|
||
This is the recommended sequence when you are uncertain about both technical feasibility and visual direction:
|
||
|
||
```bash
|
||
/gsd-spike "SSE vs WebSocket for real-time feed"
|
||
/gsd-spike --wrap-up
|
||
|
||
/gsd-sketch "real-time feed UI"
|
||
/gsd-sketch --wrap-up
|
||
|
||
/gsd-discuss-phase N
|
||
/gsd-plan-phase N
|
||
```
|
||
|
||
The spike findings inform the sketch (real data shapes, real interaction states, realistic constraints). Both wrap-ups persist decisions that the planner and UI researcher load automatically, so you do not need to re-explain choices during `/gsd-discuss-phase` or `/gsd-ui-phase`.
|
||
|
||
---
|
||
|
||
## How a spike or sketch feeds into a phase
|
||
|
||
Spike and sketch artifacts do not need to be manually referenced. GSD reads them automatically at two points:
|
||
|
||
1. **`/gsd-sketch`** — loads `.claude/skills/spike-findings-*/` before building mockups, so variants reflect proven constraints (streaming states, real field names, etc.)
|
||
2. **`/gsd-ui-phase N`** — loads `.claude/skills/sketch-findings-*/` before generating the UI design contract; pre-validated design decisions are treated as locked
|
||
|
||
The planner also reads spike findings when a `spike-findings-*` skill is present, so validated technical choices (which library, which protocol, which data format) flow directly into task plans without repeated explanation.
|
||
|
||
---
|
||
|
||
## Related
|
||
|
||
- [Design a UI phase](design-a-ui-phase.md)
|
||
- [Plan a phase](plan-a-phase.md)
|
||
- [Commands](../COMMANDS.md)
|
||
- [Docs index](../README.md)
|