msd-core/docs/how-to/verify-and-ship.md

How to verify and ship a phase

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.

---

Run user acceptance testing

/gsd-verify-work 1

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

---

When failures are found: auto-diagnose and fix planning

If any tests report issues, GSD proceeds automatically:

1. Diagnoses root causes — spawns parallel debug agents, one per issue, and updates UAT.md with root causes.
2. Plans gap closure — spawns a gsd-planner in gap-closure mode, which reads UAT.md (with diagnoses) and writes new PLAN.md files.
3. Verifies the fix plans — spawns a gsd-plan-checker to ensure the plans are executable. If issues are found, the planner and checker iterate up to three times.
4. 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.

---

When all tests pass: ship the phase

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 1

GSD 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 follow

The PR body is assembled from planning artefacts automatically:

• Phase goal from ROADMAP.md
• Per-plan summaries from SUMMARY.md files and their key files
• Requirements addressed (REQ-IDs)
• Verification status from VERIFICATION.md
• Key decisions from STATE.md

No manual body writing required.

---

Optional: code review before or after shipping

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

After the PR is open (to gate on quality before merge):

/gsd-code-review 1 --depth=deep  # Cross-file analysis including import graphs

See Set up cross-AI review to configure Gemini, Codex, or other reviewers for plan review earlier in the cycle.

---

Optional: create a clean PR branch

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.

---

Closing a milestone

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.

---

Related

• Execute a phase
• Set up cross-AI review
• The phase loop
• Commands