/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 and dispatches the task to the agent. When the agent finishes, the work lands as a clean commit. The full GSD guarantees — atomic commits, state tracking, task summaries — apply, just without the milestone ceremony.

By default, the task executes directly on your current branch (isolation: none). If you’ve opted into branch isolation (isolation: branch or isolation: worktree in preferences), GSD also creates a dedicated gsd/quick/N-slug branch and squash-merges it back to your original branch when done — leaving a single clean commit.

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.

Setup

1. 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.
2. 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.
3. Determine task number — Scans .gsd/quick/ for existing numbered directories and increments the highest number found. Returns 1 if no quick tasks exist yet.
4. Create task directory — Creates .gsd/quick/N-slug/ to hold the task summary.
5. Check isolation mode — Reads git.isolation from preferences. The default is "none" — no branch is created and work lands directly on the current branch. With "branch" or "worktree", GSD creates a dedicated branch (see Branch Isolation below).

Branch Isolation (opt-in)

Branch isolation is disabled by default. To enable it, set git.isolation in your .gsd/preferences.md:

## Git
- isolation: branch

When isolation is enabled (branch or worktree), GSD:

1. Auto-commits any dirty working tree state before switching branches.
2. Creates a git branch named gsd/quick/N-slug.
3. Writes .gsd/runtime/quick-return.json recording the original branch, quick branch, task number, slug, and description. This file survives session resets so cleanup can always run.
4. If branch creation fails for any reason, GSD continues on the current branch with a warning.

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

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

If the working tree had no staged changes after the squash (e.g., nothing was actually done), the squash commit is skipped. Cleanup runs on every turn end and is a no-op when no quick-return state exists.

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

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

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

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 for branch cleanup — only created when isolation is branch or worktree
gsd/quick/N-slug branch	Git branch for the change — only created when isolation is branch or worktree; deleted after squash-merge

Reads

File	Purpose
.gsd/quick/	Scanned to determine the next task number
.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/runtime/quick-return.json	Written on branch creation; deleted after squash-merge
Application files	Whatever the task requires

Examples

Adding a dark mode toggle (default isolation: none — no branch created):

> /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: main

  ... 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

Quick task 3 complete.

With branch isolation enabled (git.isolation: branch):

> /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.

The quick branch is squash-merged back to your original branch with commit quick(Q4): fix-null-pointer-in-user-profile-lo and then deleted.

Running without a description shows usage:

> /gsd quick

● Usage: /gsd quick <task description>

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

Related Commands

• /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