Goal: Walk executed work through user acceptance testing, diagnose and fix any failures, then open a pull request with an auto-generated body.
Prerequisites: The phase has been executed and has SUMMARY.md files. If execution is not yet done, see Execute a phase.
/gsd-verify-work 1GSD reads the phase's SUMMARY.md files, extracts user-observable deliverables, and walks you through them one at a time. For each checkpoint it presents what should happen and asks whether reality matches.
yes/y/ empty → pass, move to next test- Anything else → recorded as an issue, severity inferred from your description
You never need to categorise severity — GSD infers it from your words ("crashes" → blocker, "doesn't work" → major, "looks off" → cosmetic).
Progress is written to .planning/phases/01-<name>/01-UAT.md and survives a /clear. If a session is interrupted, re-run /gsd-verify-work 1 and GSD offers to resume from the last checkpoint.
If any tests report issues, GSD proceeds automatically:
- Diagnoses root causes — spawns parallel debug agents, one per issue, and updates
UAT.mdwith root causes. - Plans gap closure — spawns a
gsd-plannerin gap-closure mode, which readsUAT.md(with diagnoses) and writes newPLAN.mdfiles. - Verifies the fix plans — spawns a
gsd-plan-checkerto ensure the plans are executable. If issues are found, the planner and checker iterate up to three times. - Presents next step — when plans pass the checker:
Plans verified and ready for execution.
`/clear` then `/gsd-execute-phase 1 --gaps-only`
Run the suggested command to apply fixes, then re-run /gsd-verify-work 1 to confirm everything passes.
Once all UAT tests pass (or if this is your first run and no issues are found), the phase is marked complete in ROADMAP.md and STATE.md automatically.
/gsd-ship 1GSD runs preflight checks (verification status, clean working tree, branch, remote, gh CLI authentication), pushes the branch, and creates a PR:
/gsd-ship 1 # Ready-for-review PR
/gsd-ship 1 --draft # Draft PR — useful when more phases will followThe PR body is assembled from planning artefacts automatically:
- Phase goal from
ROADMAP.md - Per-plan summaries from
SUMMARY.mdfiles and their key files - Requirements addressed (REQ-IDs)
- Verification status from
VERIFICATION.md - Key decisions from
STATE.md
No manual body writing required.
/gsd-ship does not run a code review automatically, but you can slot one in at any point:
Before verification (catches issues before UAT):
/gsd-code-review 1 # Standard review
/gsd-code-review 1 --fix # Review then auto-fix Critical + Warning findingsAfter the PR is open (to gate on quality before merge):
/gsd-code-review 1 --depth=deep # Cross-file analysis including import graphsSee Set up cross-AI review to configure Antigravity, Codex, or other reviewers for plan review earlier in the cycle.
If your branch contains .planning/ commits that you do not want reviewers to see:
/gsd-pr-branch # Filter against main
/gsd-pr-branch develop # Filter against develop/gsd-pr-branch creates a new branch with only code changes — planning artefact commits are excluded. Run this before /gsd-ship if your team's review policy excludes planning noise.
A *-VERIFICATION.md reporting status: passed is re-checked, not cached, every time a completion gate reads it. Two ways it can flip to status: stale:
- Content fingerprint (default for new reports). The verifier records a digest of every input its verdict covers — the phase's
PLAN.md/SUMMARY.mdfiles, mapped requirements, and implementation files in the change set. If any of those files changes, disappears, or becomes unreadable after verification, the gate recomputes the digest, finds a mismatch, and reportsstale. This catches drift even when nothing touchesSUMMARY.mditself — an implementation file edited after verification is enough. - Legacy SUMMARY-mtime check. A
*-VERIFICATION.mdwritten before this fingerprint existed has no digest to check, so it keeps the older rule:stalewhen aSUMMARY.mdis newer than the verification report.
Either way, stale routes the same as any other incomplete state: re-run /gsd-verify-work 1 before shipping.
The content fingerprint hashes covered files exactly as they sit on disk, including line endings. A checkout without a .gitattributes eol=lf rule pinning text files to LF (a Windows checkout with core.autocrlf=true, for example) can report stale on unchanged content — fix with a .gitattributes eol=lf rule, not by treating it as drift.
If this was the last phase in the milestone, run the milestone audit and archive it:
/gsd-audit-milestone # Verify all requirements shipped
/gsd-complete-milestone # Archive, create git tag/gsd-complete-milestone is the natural next step after the PR merges. See the The phase loop for how verification and shipping fit into the full project lifecycle.