3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
125 lines
4.3 KiB
Markdown
125 lines
4.3 KiB
Markdown
# 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](execute-a-phase.md).
|
|
|
|
---
|
|
|
|
## Run user acceptance testing
|
|
|
|
```bash
|
|
/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.
|
|
|
|
```bash
|
|
/gsd-ship 1
|
|
```
|
|
|
|
GSD runs preflight checks (verification status, clean working tree, branch, remote, `gh` CLI authentication), pushes the branch, and creates a PR:
|
|
|
|
```bash
|
|
/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):
|
|
|
|
```bash
|
|
/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):
|
|
|
|
```bash
|
|
/gsd-code-review 1 --depth=deep # Cross-file analysis including import graphs
|
|
```
|
|
|
|
See [Set up cross-AI review](set-up-cross-ai-review.md) 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:
|
|
|
|
```bash
|
|
/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:
|
|
|
|
```bash
|
|
/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](../explanation/the-phase-loop.md) for how verification and shipping fit into the full project lifecycle.
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- [Execute a phase](execute-a-phase.md)
|
|
- [Set up cross-AI review](set-up-cross-ai-review.md)
|
|
- [The phase loop](../explanation/the-phase-loop.md)
|
|
- [Commands](../COMMANDS.md)
|