Finalize a wave — PR review, merge sequencing, issue cleanup, worktree cleanup, and handoff to retro
Finalize a wave by reviewing all open PRs, merging in dependency order, closing resolved issues, and cleaning up. This is the exit gate before running /wave-retro.
List all PRs targeting the wave's deployment branch:
gh pr list --state open --base "deployments/phase{P}/wave-{M}" --json number,title,author,headRefName,reviews,isDraft,createdAt
Also check for PRs targeting main that belong to this wave (by label or branch pattern):
gh pr list --state open --base main --label "p{P}-wave-{M}" --json number,title,author,headRefName,reviews
For each open PR:
gh pr checks {NUMBER} --json name,conclusion,status
Classify each PR:
| Status | Criteria | Action |
|---|---|---|
| Ready | CI green, has peer review | Merge |
| Needs review | CI green, no peer review | Request review |
| CI failing | CI red | Fix before merge |
| Draft | Marked as draft | Exclude (report only) |
| Blocked | Has unmerged dependency | Defer until dependency merges |
Build a merge dependency graph:
Depends on #N or After #N referencesPresent the proposed merge sequence:
**Merge Sequence: Phase {P} Wave {M}**
| Order | PR | Title | Status | Dependencies | Action |
|-------|-----|-------|--------|--------------|--------|
| 1 | #N | ... | Ready | None | Merge |
| 2 | #N | ... | Ready | After #M | Merge |
| — | #N | ... | CI failing | — | Fix first |
| — | #N | ... | Draft | — | Skip |
Do NOT merge any PRs until the user approves the sequence.
For each PR marked "Ready", perform a review using charter format (same as /review-pr):
gh pr diff {NUMBER}
Post review comment:
Requestor: {Reviewer.Name}
Requestee: {PR author}
RequestOrReplied: Request
**Review: {LGTM or issues}**
Must-fix: {list or "None"}
Tech-debt: {list or "None"}
For each tech-debt item, create a GitHub Issue labeled tech-debt and the next wave/phase label.
If must-fix items are found, do NOT merge — report and wait for fixes.
After user approval, merge in the determined order:
gh pr merge {NUMBER} --merge --delete-branch
After each merge, verify:
If a merge introduces CI failures, stop and report before continuing.
Run /wave-audit logic to close issues resolved by the merged PRs:
# For each merged PR, check for Closes/Fixes/Resolves references
gh pr view {NUMBER} --json body
Close referenced issues with audit comments. Also check for issues matched by branch naming convention.
Check that all wave issues are resolved:
gh issue list --state open --label "p{P}-wave-{M}" --json number,title
For any remaining open issues:
All wave worktrees MUST be removed before the wrapup is considered complete. Stale worktrees accumulate across waves and cause branch contention.
# Prune any stale worktree metadata
git worktree prune
# List all worktrees and identify wave-related ones
git worktree list
# Remove each wave worktree (branches matching wave assignees)
# Example: git worktree remove .claude/worktrees/W.Mwangi+0063-fix-branch-freshness-worktree --force
For each worktree:
git -C <path> status --porcelain)git worktree remove <path>git push origin --delete <branch>Report what was cleaned:
**Worktree Cleanup:**
- Removed: {count} worktrees
- Skipped (dirty): {count}
- Remote branches deleted: {count}
Why: Phase 2 Wave 1 left 6 stale worktrees after merge because cleanup wasn't enforced.
Check if any merged PRs affect documentation:
# List files changed across all merged PRs
for pr in {merged_pr_numbers}; do
gh pr diff "$pr" --name-only
done
Flag any changes to:
**Wave Wrapup: Phase {P} Wave {M}**
**PRs:**
- Merged: {count}
- Deferred: {count} (moved to next wave)
- Still failing CI: {count}
**Issues:**
- Closed: {count}
- Remaining open: {count} (deferred)
**Tech-debt created:** {count} new issues
**Documentation:** {docs updated | docs need update | no doc changes}
**Worktrees cleaned:** {count}
**Next step:** Run `/wave-retro` for full retrospective with assessments and trust updates.
If this is the final wave of the phase:
# Create PR from deployments branch to main
gh pr create --base main --head "deployments/phase{P}/wave-{M}" \
--title "Phase {P} Wave {M} → main" \
--body "Final wave merge. All PRs reviewed and merged to deployment branch."
Do NOT merge to main without user approval. This is a significant action that affects all downstream repos.
Run /ontology-rebuild to process any files that changed during this wave. This ensures the ontology reflects the current state of all repos before the wave closes.
ontology/checksums.json, report "Ontology: up to date" and skipRun /annunaki-attack to process any errors captured by the Annunaki monitor during this wave. This converts observed errors into preventative automation (hooks, skills, charter updates) before the wave closes.
.claude/annunaki/errors.jsonl is empty or missing, report "Annunaki: No errors captured this wave" and skipExamine all memory files in the project memory directory for entries that describe behaviors, rules, or patterns that could be codified as a hook, skill, or charter update instead of remaining as soft memory.
Process:
Read all memory files:
ls ~/.claude/projects/*/memory/*.md
For each memory file, classify it:
| Category | Criteria | Action |
|---|---|---|
| Hook candidate | Describes a rule that should be enforced automatically (e.g., "always do X before Y", "never do Z") | Create the hook, add to settings.json, create GH issue for bookkeeping |
| Skill candidate | Describes a repeatable multi-step workflow (e.g., "when doing X, follow these steps") | Create the skill in .claude/skills/, create GH issue |
| Charter update | Describes a process rule or convention that should be documented for all agents | Update the relevant charter section, create GH issue |
| Keep as memory | User-specific context, preferences, or project state that doesn't fit the above | Leave as-is |
For each hook/skill/charter candidate: a. Create a GitHub Issue describing the automation opportunity b. Assign to the best-fit team member based on the charter mapping:
Report what was converted:
**Memory-to-Automation Audit**
| Memory File | Classification | Action Taken | Issue |
|-------------|---------------|--------------|-------|
| feedback_x.md | Hook | Created validate_x.py | #N |
| project_y.md | Keep | No action | — |
| ... | ... | ... | ... |
Why: Memory files accumulate rules and patterns that should be enforced automatically. If a memory says "always do X", that's a hook. If it says "follow these steps for Y", that's a skill. Leaving these as memories means they only work when the LLM happens to load them — hooks and skills are deterministic.
Designated owner: Aino Virtanen handles most conversions (hooks, charter, standards). The orchestrator spawns her with the audit list and she reports back when done.
/wave-retro must be run separately after wrapup completes