/gsd quick

What It Does

/gsd quick is the lightweight path for small, self-contained changes. Instead of creating a milestone, roadmap, and slices, it skips the entire planning hierarchy and dispatches a single task directly.

You describe what you want in plain English, and GSD creates a numbered task directory, a dedicated git branch, and dispatches the task to the agent. When the agent finishes, GSD squash-merges the quick branch back into your original branch and deletes it — leaving a single clean commit. The full GSD guarantees — atomic commits, state tracking, task summaries — apply, just without the milestone ceremony.

Use /gsd quick when the change is small enough that planning overhead isn’t worth it: fixing a bug, adding a config option, updating a dependency, writing a utility function.

Usage

/gsd quick <task description>

Everything after quick is captured as the description. Surrounding quotes are stripped by the shell but are otherwise optional — GSD itself just trims leading and trailing whitespace.

/gsd quick fix the login button color
/gsd quick "add dark mode toggle to the settings page"
/gsd quick update the README with new API endpoints

How It Works

Quick mode bypasses the milestone/slice/task hierarchy entirely. No roadmap, no slice plan, no dispatch loop. It’s a direct path from description to execution — including automated cleanup when the task is done.

Setup

Validate .gsd/ — Checks that a GSD project exists. If not, prompts you to run /gsd to initialize a project first. Quick tasks still need the GSD project structure, even though they skip milestones.
Generate slug — Converts your description into a URL-safe slug (e.g., "fix the login button color" → fix-the-login-button-color), truncated to 40 characters.
Determine task number — Scans .gsd/quick/ for existing numbered directories and increments the highest number found. Returns 1 if no quick tasks exist yet.
Create branch — Creates a git branch named gsd/quick/N-slug. If your working tree has uncommitted changes, GSD auto-commits them first before switching. If branch creation fails for any reason, GSD continues on the current branch with a warning.
Persist return state — Writes .gsd/runtime/quick-return.json recording the original branch, quick branch, task number, slug, and description. This survives session resets so cleanup can always run.
Create task directory — Creates .gsd/quick/N-slug/ to hold the task summary.

Execution

The task is dispatched as a focused prompt containing the description, branch name, summary path, date, task number, and slug. The agent:

Follows any GSD Skill Preferences present in system context
Reads relevant code before modifying — no stubs or placeholders
Writes or updates tests where appropriate
Handles error cases and edge cases
Commits changes atomically using conventional commit messages (feat:, fix:, refactor:, etc.)
Writes a structured summary to .gsd/quick/N-slug/N-SUMMARY.md
Adds a row to the “Quick Tasks Completed” table in .gsd/STATE.md and updates the “Last activity” line

The agent finishes by saying "Quick task N complete." — no multi-unit dispatch, no research/plan/execute phases.

Branch Cleanup

After the agent finishes, GSD automatically cleans up the quick branch:

Auto-commit remaining changes — Any uncommitted work on the quick branch is committed before cleanup.
Checkout original branch — Switches back to the branch that was active when /gsd quick was invoked.
Squash-merge — Runs git merge --squash gsd/quick/N-slug, staging all quick branch changes as a single set of modifications.
Squash commit — Creates a single commit with the message quick(Q<N>): <slug> (e.g., quick(Q3): fix-the-login-button-color).
Delete quick branch — Removes the gsd/quick/N-slug branch.
Clear runtime state — Deletes .gsd/runtime/quick-return.json.

The result is one clean commit on your original branch, with no leftover quick branches. If the working tree had no staged changes after the squash (e.g., nothing was actually done), the squash commit is skipped.

Summary Format

Each quick task produces a N-SUMMARY.md file in its task directory:

# Quick Task: fix the login button color

**Date:** 2026-01-15
**Branch:** gsd/quick/3-fix-the-login-button-color

## What Changed
- Updated primary button color token in theme.ts
- Fixed hover state for disabled buttons

## Files Modified
- src/styles/theme.ts
- src/components/Button.tsx

## Verification
- Ran component tests — all passing
- Visually verified in Storybook

STATE.md Tracking

After completion, the agent updates .gsd/STATE.md to record the task in a “Quick Tasks Completed” table and updates the “Last activity” line:

| # | Description | Date | Commit | Directory |
|---|-------------|------|--------|-----------|
| 3 | fix the login button color | 2026-01-15 | a1b2c3d | [3-fix-the-login-button-color](./quick/3-fix-the-login-button-color/) |

If the section doesn’t exist yet, the agent creates it after the “Blockers/Concerns” section.

What Files It Touches

Creates

File	Purpose
`.gsd/quick/N-slug/`	Task directory
`.gsd/quick/N-slug/N-SUMMARY.md`	Summary of what was done
`.gsd/runtime/quick-return.json`	Persisted return state (original branch, quick branch, task info) for cleanup across session resets
`gsd/quick/N-slug` branch	Git branch for the change (deleted after squash-merge)

Reads

File	Purpose
`.gsd/quick/`	Scanned to determine the next task number
`.gsd/STATE.md`	Read before updating the quick tasks table
`.gsd/runtime/quick-return.json`	Read during cleanup to determine squash target and original branch

Writes

File	Purpose
`.gsd/quick/N-slug/N-SUMMARY.md`	Task summary written by agent
`.gsd/STATE.md`	”Quick Tasks Completed” table row added; “Last activity” line updated
`.gsd/runtime/quick-return.json`	Written on branch creation; deleted after squash-merge
Application files	Whatever the task requires

Examples

Adding a dark mode toggle:

> /gsd quick add dark mode toggle to the settings page

● Quick task 3: add dark mode toggle to the settings page
  Directory: .gsd/quick/3-add-dark-mode-toggle-to-the-settings
  Branch: gsd/quick/3-add-dark-mode-toggle-to-the-settings

  ... agent executes task ...

  ✓ Added ThemeToggle component
  ✓ Wired into settings page
  ✓ Dark mode CSS variables added
  ✓ Summary written to .gsd/quick/3-add-dark-mode-toggle-to-the-settings/3-SUMMARY.md
  ✓ STATE.md updated

Quick task 3 complete.

The quick branch is squash-merged back to your original branch with commit quick(Q3): add-dark-mode-toggle-to-the-settings and then deleted.

Fixing a bug quickly:

> /gsd quick fix null pointer in user profile loader

● Quick task 4: fix null pointer in user profile loader
  Directory: .gsd/quick/4-fix-null-pointer-in-user-profile-lo
  Branch: gsd/quick/4-fix-null-pointer-in-user-profile-lo

  ... agent executes task ...

Quick task 4 complete.

Running without a description shows usage:

> /gsd quick

● Usage: /gsd quick <task description>

  Example: /gsd quick fix login button not responding on mobile

Prompts Used

quick-task — Lightweight task execution prompt

/gsd capture — Save a thought for later without executing immediately
/gsd auto — Full continuous execution for milestone-based work
/gsd steer — Direct override when active work needs redirecting
/gsd history — Review what quick tasks and units have been executed

Previous
/gsd stop Next
/gsd discuss