Lesson 09 | GSD Q&A (Part 3): Practical Tips & Troubleshooting

Chapter 3: Practical Tips & Troubleshooting

What to do when things go wrong, how to onboard existing projects, and daily usage tips.

Q15: How do I roll back execution errors? Can GSD undo?

GSD has no dedicated "undo" command. But atomic commits make git rollbacks easy:

# View recent commits
git log --oneline -10

# Revert to a specific commit (keeping workspace changes)
git reset --soft <commit-hash>

# Revert to a specific commit (discarding all changes)
git reset --hard <commit-hash>

# Revert just one specific commit
git revert <commit-hash>

Each Task is an independent commit, so you can precisely roll back to just before the failing Task.

Recommendation: Manually git tag before major Phases begin, e.g., git tag before-phase-3. To roll back, simply git reset --hard before-phase-3.

Q16: What if AI code quality is poor? Can I ask it to rewrite?

Yes. Three ways:

1. /gsd-code-review + /gsd-code-review-fix: Auto review + auto fix. The review report categorizes by severity, and the fix agent only modifies problematic areas.
2. Modify directly: Use /gsd-quick to tell AI what is wrong and how to fix it. Or fix it manually.
3. Re-execute: git revert the problematic commit, then re-run /gsd-execute-phase --wave N for that specific wave.

Pro-tip: Don't wait until the entire Phase finishes to check the code. Use --interactive mode to check after every Task.

Q17: What if the research agent fails? Can I fill it in manually?

Research agents can fail due to network issues or API limits (which happened in this tutorial project).

How to respond:

1. Retry: Simply re-run /gsd-new-project, and the research phase will try again.
2. Fill manually: Do your own research and write the results into the .planning/research/ directory. Formatting doesn't matter much; AI can read Markdown.
3. Skip: Use --skip-research to skip research and jump straight to the requirements phase. Your own domain knowledge will suffice.

Failed research doesn't block the rest of the flow. Requirements can be written or supplemented manually.

Q18: How do I introduce GSD to an existing project? Do I need to refactor?

No refactoring needed. Two-step integration:

1. Create a CLAUDE.md in the project root outlining constraints.
2. Run /gsd-new-project, and GSD will read existing code to generate plans.

GSD won't modify existing code. It only generates planning files in .planning/. Subsequent Phases can incrementally add features.

Note: Existing projects might require you to supplement the requirements document. GSD tries to infer requirements from code analysis, but it may not be 100% accurate. Manual checking of REQUIREMENTS.md is recommended.

Q19: GSD generates too many files, can I slim down .planning/?

Yes. Files in .planning/ fall into two categories:

Core Files (Do not delete):

• STATE.md — Project state, essential for restoring progress in new sessions
• ROADMAP.md — Roadmap, essential for executing Phases
• REQUIREMENTS.md — Requirements, essential for Verification
• phases/*/CONTEXT.md — Frozen decisions, downstream Phases rely on this

Deletable Files (Deleting won't affect functionality):

• research/ — Research outputs, delete after decisions are made
• phases/*/DISCUSSION-LOG.md — Discussion logs, purely for reference
• phases/*/VERIFICATION.md — Verification reports, can be deleted after the Phase passes
• phases/*/REVIEW.md — Review reports, can be deleted after fixes

Pro-tip: Once a Phase passes verification, keep only PLAN.md and CONTEXT.md. Delete research, discussion, and verification files. Always keep STATE.md.

Q20: What is the difference between solo use and team collaboration with GSD?

Solo Use (This tutorial scenario):

• GSD replaces the discipline of "Plan → Execute → Check"
• AI acts out all roles (Product/Design/Dev/QA)
• .planning/ is your personal memo

Team Collaboration:

• The .planning/ directory can be committed to git so team members share context
• CONTEXT.md acts as a design document for team review
• PLAN.md acts as task allocation; multiple people can execute different Phases in parallel
• VERIFICATION.md serves as acceptance criteria
• REVIEW.md serves as the Code Review log

Core difference: Solo, GSD means "AI helps you manage the project." In a team, GSD means "AI helps the team align on context."

---

Tutorial Complete! Full series 14 episodes + 4 appendices, 6 acts, and 20 Q&A.