Lesson 08 | GSD Q&A (Part 2): Workflow Details

Chapter 2: Workflow Details

What each command specifically does, what can be skipped, and how to customize.

Q8: What exactly does /gsd-new-project do? Can I skip it?

Full flow:

1. Question phase: Asks for project name, description, target users, tech constraints
2. Research phase: Runs 4 parallel research agents (domain/stack/architecture/ecosystem), outputs research files
3. Requirements phase: Generates REQUIREMENTS.md based on research + your answers
4. Roadmap phase: Organizes requirements into dependency-based Phases, generates ROADMAP.md
5. Initialization phase: Creates STATE.md, config.json, CLAUDE.md

Can be skipped:

• --auto skips questions, infers automatically from current chat context
• --skip-research skips research (if you already have domain knowledge)
• Roadmap and requirements can be manually edited once generated

Cannot be skipped: Requires at least a project name and basic description.

Q9: Who is /gsd-discuss-phase discussing with? Can I skip straight to coding?

Discussing with Claude AI. It plays the role of an "experienced colleague", asking questions you hadn't considered.

Typical discussion points:

• "Are you sure you want to use eval()? There are security risks."
• "There are three options for floating-point precision, which fits your scenario?"
• "How many history entries maximum? Why not infinite?"

Can be skipped. You can jump straight to /gsd-plan-phase. But skipping risks:

• AI making decisions on its own that don't match your expectations
• Reworking later when issues arise

Recommendation: Discuss at least the first Phase. Later Phases can be skipped if they are simple.

Q10: What do plans generated by /gsd-plan-phase look like? Can I modify them?

Plans are Markdown files stored in .planning/phases/XX/PLAN-YY.md.

Typical structure:

## Plan 01: Parser + Basic Math
- Task 1: Implement tokenize() function [TDD]
  - Red: Write test tokenize("2+3") → ["2", "+", "3"]
  - Green: Implement tokenize()
  - Refactor: Handle edge cases
- Task 2: Implement shuntingYard() [TDD]
  - ...

Can be modified. The plan is just a Markdown file—edit away. When done, /gsd-execute-phase will read the new version.

Pro-tip: If you only want to change a part, just edit the PLAN.md file directly instead of re-running /gsd-plan-phase.

Q11: Will /gsd-execute-phase auto-commit code? Can I control it?

Default behavior:

• Automatically git commit after each Task finishes (atomic commits)
• Auto-generates commit messages describing what was done
• Appends Co-Authored-By: Claude tag

Control methods:

• --auto: Fully automatic, no questions asked
• --interactive: Confirms before each Task
• --wave N: Only executes wave N (manually control pace)
• --gaps-only: Only fixes parts that failed verification

If you don't want auto-commits: Use --interactive mode, or manually git reset after execution (atomic commits make reverting easy).

Q12: What if I realize halfway through a Phase that the direction is wrong?

Three choices:

1. Revert: git log to find the commit before the error, git revert. Atomic commits mean each Task can be independently reverted.
2. Fix: Use /gsd-quick to modify specific files. Don't re-run the whole flow.
3. Re-plan: Re-run /gsd-discuss-phase + /gsd-plan-phase, keeping existing code.

GSD isn't afraid of making mistakes. Atomic commits + .planning/ logs make fixes cheap.

Q13: What's the difference between /gsd-verify and me checking it myself?

The difference is systematicity and objectivity.

Self-checking:

• Easy to miss things ("Looks fine to me")
• Tends to only look at code, not goals (Code is written, but requirement wasn't met)

/gsd-verify:

• Reads Phase goals in PLAN.md
• Checks item by item: "Does code exist for this goal? Is the logic correct?"
• Generates VERIFICATION.md: Pass/Partial/Fail, with evidence for each
• Doesn't look at "how many Tasks you did", looks at "were the goals achieved"

Analogy: Self-checking is taking a practice test; /gsd-verify is an independent audit.

Q14: When do I use /gsd-quick vs the full workflow?

/gsd-quick is for:

• Changing a CSS value
• Fixing a bug
• Adding a comment
• Updating docs
• Anything doable within 5 minutes

Full workflow (discuss → plan → execute → verify) is for:

• Adding new features (affecting multiple files)
• Architecture changes (affecting existing code structure)
• Requirement changes (needing REQUIREMENTS.md updates)

Criteria: Will this change affect other parts? Yes → full workflow. No → quick.