/gsd-guide

name: gsd-guide
description: GSD tutorial, command reference, and workflow explainer. Explains what a GSD workflow command does before you run it. Activates when user is new to GSD, asks about commands, wants to understand workflows, or mentions preview.
format: 2025-10-02
version: 1.0.0
status: ACTIVE
updated: 2026-04-15
triggers:
  - "user is new to GSD, asks about commands, wants to understand workflows, or mentions preview"

GSD Guide — Quick Reference + Workflow Explainer

Combines the GSD tutorial/command reference (formerly `gsd-onboard`) with the per-command workflow explainer (formerly `gsd-explain`). Section 1 is the compact reference; Section 2 is the detailed "what will this do before I run it" explainer.

---

Section 1 — Quick Reference

**GSD** = question → research → plan → execute → verify.

Files

.planning/
├── PROJECT.md       # Vision, decisions
├── REQUIREMENTS.md  # REQ-IDs
├── ROADMAP.md       # Phases
├── STATE.md         # Current position
├── config.json      # Settings
├── phases/NN-name/  # Plans + summaries
└── milestones/      # Archives

Commands

| Command | Purpose | |---------|---------| | /gsd:new-project | Init project | | /gsd:new-milestone | New version | | /gsd:progress | State + next action | | /gsd:discuss-phase N | Gather context | | /gsd:plan-phase N | Create plans | | /gsd:execute-phase N | Build plans | | /gsd:quick | Small tasks | | /gsd:verify-work N | Test deliverables | | /gsd:audit-milestone | Completion check | | /gsd:complete-milestone | Archive | | /gsd:debug | Debug with state | | /gsd:pause-work | Checkpoint | | /gsd:resume-work | Restore |

Workflow

plan-phase N → /clear → execute-phase N → verify-work N

Concepts

• **Atomic commits:** One per plan, surgical rollback
• **Fresh context:** `/clear` + STATE.md
• **Wave execution:** Parallel independent plans
• **Modes:** yolo (auto) or interactive

---

Section 2 — Detailed Explanations

Helps users understand what a GSD command will do before they run it, reducing hesitation and preventing incorrect usage.

When to Use

Activate when the user:

• Asks "what does /gsd:plan-phase do?"
• Wants to preview changes before running a command
• Is learning GSD and needs explanations
• Mentions wanting to understand a workflow

What This Skill Does

1. **Reads the workflow file** from `.claude/get-shit-done/workflows/` 2. **Parses the workflow structure** (trigger, purpose, process steps) 3. **Explains in plain language** what will happen 4. **Shows file previews** (what files will be created/modified) 5. **Estimates resources** (time, context usage, user prompts)

Explanation Template

When explaining a GSD workflow, use this structure:

## /gsd:command-name - [Purpose]

**What it does:**
[2-3 sentence overview]

**Process:**
1. [First step - what happens]
2. [Second step - what happens]
3. [Third step - what happens]

**Files created/modified:**
- `.planning/path/to/file.md` - [purpose]
- `.planning/other/file.json` - [purpose]

**Agents spawned:**
- `agent-name` (model) - [what it does]

**User interaction:**
- [Number] prompts expected
- [Type of input needed]

**Estimated:**
- Time: [duration estimate]
- Context: [percentage of window]

**After completion:**
- [What state the project will be in]
- [Next recommended command]

Key Workflows to Explain

Initialization Workflows

**`/gsd:new-project`**

• Spawns 4 parallel researchers (stack, features, architecture, pitfalls)
• Creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md
• Estimates: 15-30 minutes, high context usage
• User prompts: 10-15 questioning rounds

**`/gsd:new-milestone`**

• Updates PROJECT.md with new milestone context
• Creates new REQUIREMENTS.md for milestone scope
• Routes to roadmap creation
• Estimates: 5-10 minutes
• User prompts: 5-8 for requirements

Planning Workflows

**`/gsd:discuss-phase N`**

• Gathers user vision for phase before planning
• Creates `.planning/phases/NN-name/NN-CONTEXT.md`
• No agents spawned (direct conversation)
• Estimates: 3-5 minutes
• User prompts: 5-10 contextual questions

**`/gsd:plan-phase N`**

• Optionally spawns `gsd-phase-researcher` (if enabled)
• Spawns `gsd-planner` to create PLAN.md files
• Spawns `gsd-plan-checker` to verify plans
• Creates multiple plan files (`NN-01-PLAN.md`, `NN-02-PLAN.md`, …)
• Estimates: 3-8 minutes
• User prompts: 0-2 (only if plan checker finds issues)

**`/gsd:research-phase N`**

• Spawns `gsd-phase-researcher` standalone
• Creates `NN-RESEARCH.md` with findings
• WebSearch intensive
• Estimates: 5-10 minutes
• User prompts: 0

Execution Workflows

**`/gsd:execute-phase N`**

• Spawns `gsd-executor` agents (1 per wave)
• Executes all plans in phase with parallelization
• Creates `NN-NN-SUMMARY.md` for each plan
• Atomic commits per plan
• Estimates: Varies widely by plan complexity
• User prompts: 0 in YOLO mode, varies in interactive mode

**`/gsd:quick`**

• Lightweight execution without full planning
• Single `gsd-executor` agent
• Creates STATE.md entry
• Atomic commit
• Estimates: 2-5 minutes
• User prompts: 0

Validation Workflows

**`/gsd:verify-work N`**

• Spawns `gsd-verifier` agent
• UAT-style testing of phase deliverables
• Creates VERIFICATION.md report
• Estimates: 3-7 minutes
• User prompts: Multiple (testing scenarios)

**`/gsd:audit-milestone`**

• Spawns `gsd-verifier` and `gsd-integration-checker`
• Comprehensive completion check
• Creates MILESTONE-AUDIT.md
• Estimates: 5-10 minutes
• User prompts: 0

File Structure Reference

Help users visualize what files GSD creates:

.planning/
├── PROJECT.md           # Vision, requirements, decisions
├── REQUIREMENTS.md      # What we're building (REQ-IDs)
├── ROADMAP.md           # Phase structure and status
├── STATE.md             # Session memory, current position
├── config.json          # Workflow preferences
│
├── phases/
│   ├── 01-foundation/
│   │   ├── 01-CONTEXT.md      #