| name | post-pr-review |
| description | Post-merge checklist for archiving, documentation, versioning, and release tagging. Use when completing post-merge cleanup, archiving tracking files, updating docs, or running the pre-merge strategic assessment (Step 6). DO NOT USE FOR: pre-PR readiness checks (use verification-before-completion) or processing GitHub review comments (use code-review-intake). |
| provides | post-pr |
| suggested-next-step | Run /orchestrate {ISSUE} or follow post-pr-review skill workflow |
Post-PR Review
When to Use
Execute this workflow after:
- Pull Request has been reviewed
- All feedback has been addressed
- PR has been merged to the main branch
- CI/CD pipeline has completed successfully
Or use the strategic assessment section only (Step 6) before merging to evaluate design alignment and long-term implications before approving a PR.
Note for plugin-only users: Step 6 (Strategic Assessment) is available without cloning — it's pure analysis using GitHub tools.
Purpose
This document provides a standardized checklist for agents to follow after a Pull Request has been reviewed, approved, and merged. These steps ensure proper cleanup, documentation, and project maintenance.
Standard Post-Merge Checklist
1. Archive Tracking Files
Action: Move completed tracking files into the local archive. These directories are gitignored — they stay on your machine only.
# Preferred: use the cleanup script (handles archival, branch deletion, git sync).
# The script is shipped with the agent-orchestra plugin/clone and self-resolves its paths.
pwsh "skills/session-startup/scripts/post-merge-cleanup.ps1" -IssueNumber {ID} -FeatureBranch feature/issue-{ID}-description
# Optional: also pass sibling worktrees or orphan branches for composite cleanup (see session-startup SKILL.md § Permission allowlist):
# pwsh "skills/session-startup/scripts/post-merge-cleanup.ps1" -IssueNumber {ID} -FeatureBranch feature/issue-{ID}-description -OrphanBranches @('claude/old-branch') -SiblingWorktrees @('path/to/worktree')
# Or manual archive only (PowerShell):
$archivePath = Join-Path ".copilot-tracking-archive" (Get-Date -Format 'yyyy') (Get-Date -Format 'MM') "issue-{ID}"
New-Item -Path $archivePath -ItemType Directory -Force
Get-ChildItem .copilot-tracking -Recurse -File |
Where-Object { (Get-Content $_.FullName -Raw) -match 'issue_id:\s*{ID}' } |
ForEach-Object { Move-Item -LiteralPath $_.FullName -Destination $archivePath }
Note: Both .copilot-tracking/ and .copilot-tracking-archive/ are gitignored. These files are agent scaffolding — the durable record lives in GitHub issues, PRs, commits, and Documents/Design/. Do not commit tracking files.
Verify:
- Files moved to
.copilot-tracking-archive/{year}/{month}/issue-{ID}/
- No tracking files remain in
.copilot-tracking/research/ for this issue
Automation: The plugin's SessionStart hook detects stale tracking files, sibling worktrees, and orphan branches and prompts you at the start of your next conversation — cleanup requires one confirmation and runs as a single composite pwsh ...post-merge-cleanup.ps1 ... invocation (no per-branch permission prompts). You can also run the script directly: pwsh "skills/session-startup/scripts/post-merge-cleanup.ps1" -IssueNumber {ID} -FeatureBranch feature/issue-{ID}-description (script path is relative to the agent-orchestra plugin or repo clone). See the ### Permission allowlist (recommended) subsection in skills/session-startup/SKILL.md for opt-in allowlist entries that suppress the single prompt.
2. Update Documentation
Action: Ensure all relevant documentation reflects the changes.
Common Documentation to Review:
Guidelines:
- Be specific about what changed
- Include version numbers where applicable
- Link to related issues or PRs
- Update any diagrams or visual documentation
3. Version Badge Updates (If Applicable)
Action: Use the bump-version script to update version strings consistently across all files in one invocation:
pwsh .github/scripts/bump-version.ps1 -Version X.Y.Z -DryRun # preview first
pwsh .github/scripts/bump-version.ps1 -Version X.Y.Z # apply
The script updates plugin.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json (2 occurrences), .github/plugin/marketplace.json (2 occurrences), and README.md (badge line) — 7 occurrences across 5 files. It validates pre-bump consistency and exits with an error if any file has drifted.
Plugin-only users (scripts not distributed via plugin): If you're using this workflow as a plugin install without cloning, use targeted replace_string_in_file edits for each file individually, then commit and push.
WRONG (do not use):
# mcp_github_create_or_update_file with partial file content
# This tool REPLACES the entire file. Only use it for net-new files.
# Using it with partial content silently truncates the rest of the file.
Rule: mcp_github_create_or_update_file is only safe for new files. For any edit to an existing file, use the bump script (cloned repo) or replace_string_in_file + git commit + git push (plugin-only).
4. Tag Releases (If Applicable)
Action: Create version tags for significant releases.
When to Tag:
- Feature releases (minor version bump)
- Bug fix collections (patch version bump)
- Breaking changes (major version bump)
- Milestone completions
Semantic Versioning:
MAJOR.MINOR.PATCH (e.g., v1.2.3)- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes (backward compatible)
Process:
git tag -a v1.2.0 -m "Release version 1.2.0: Added feature X"
git push origin v1.2.0
Release Notes:
- Summarize changes from CHANGELOG
- Highlight breaking changes
- Include upgrade instructions if needed
5. Clean Up Branches
Action: Remove merged feature branches.
git branch -d feature/issue-{ID}-description
git push origin --delete feature/issue-{ID}-description
Note: Some projects auto-delete branches on PR merge. Verify your project settings.
Automation: Branch deletion is also handled by skills/session-startup/scripts/post-merge-cleanup.ps1 when invoked via the "Session Startup Check" cleanup flow (see Section 1 above).
6. Strategic Assessment (Pre-Merge)
Action: Before approving a PR, evaluate strategic alignment on three dimensions.
Design Alignment:
- Does the implementation match the design doc (
Documents/Design/{domain}.md)?
- Are any design decisions reversed or partially implemented?
- If the design doc doesn't exist yet, does the implementation align with the issue's stated goals?
Roadmap Integration:
- Does this change fit the project's stated direction?
- Any unintended coupling introduced that will constrain future work?
- Are there deprecations triggered or migration concerns created?
Long-Term Implications:
- Tech debt introduced — is it tracked (labeled issue or comment)?
- Are there performance, scale, or maintenance concerns not covered in tests?
- Would this pass the "6-month-later developer" readability test?
Output: Emit one of:
✅ Strategic assessment: aligned — no concerns⚠️ Strategic assessment: concerns noted — list specific items; may block PR⏭️ Strategic assessment: skipped — {reason} — e.g., documentation-only change
7. Update Project Tracking
Action: Close related issues. The portfolio tracker issue updates automatically.
The derived portfolio tracker (Documents/Planning/sequence.yaml + render-portfolio.yml workflow) re-renders the control-tower issue after every merge to main — no manual board update is required. The board model (ranked-umbrella zones, derived Triage) is documented in Documents/Design/control-tower-v2.md.
Manual fallback (if the workflow did not run or needs a forced refresh):
# Guard: skip silently in consumer repos that lack the renderer
if ((Test-Path 'Documents/Planning/sequence.yaml') -and (Test-Path '.github/scripts/render-portfolio.ps1')) {
pwsh .github/scripts/render-portfolio.ps1
}
Consumer repos: if Documents/Planning/sequence.yaml or .github/scripts/render-portfolio.ps1 is absent, this step is a no-op — skip silently.
Verification:
8. Notify Stakeholders (If Applicable)
Action: Communicate completion to relevant parties.
Notification Scenarios:
- Feature releases → Announce to users/team
- Breaking changes → Alert dependent teams
- Bug fixes → Notify affected users
- Security patches → Follow security disclosure process
Communication Channels (adapt to your project):
- GitHub issue comments
- Team chat channels
- Email notifications
- Release announcements
- Documentation updates
Validation Checklist
Before considering work fully complete, verify:
Project-Specific Customization
[CUSTOMIZE] Add project-specific steps:
- Deployment procedures
- Database migration verification
- Cache invalidation
- CDN purging
- Monitoring setup
- Alert configuration
- Dependency updates
- Security scans
- Performance benchmarks
Emergency Rollback
If critical issues are discovered post-merge:
- Immediate: Revert the merge commit
- Communication: Alert team and stakeholders
- Investigation: Identify root cause
- Resolution: Create hotfix PR
- Documentation: Record incident and resolution
git revert -m 1 <merge-commit-hash>
git push origin main
Completion
Once all checklist items are verified:
- Mark the original issue as closed
- Remove any temporary resources
- Archive any temporary documentation
- Verify control-tower issue updated (auto-rendered by workflow after merge)
The work is now fully complete and properly documented.
Structured Outcome Contract
When invoked from Code-Conductor's post-merge cleanup path, this skill returns a structured outcome hashtable with the following shape:
@{
archive = 'passed' | 'failed' | 'skipped'
docs = 'passed' | 'failed' | 'skipped'
version = 'passed' | 'failed' | 'skipped'
releaseTag = 'passed' | 'failed' | 'skipped'
}
Per-key outcome determination:
archive: passed when tracking files were moved/archived and git status is clean; failed when archiving was attempted but incomplete; skipped when no tracking files existed.docs: passed when README, CLAUDE.md, or ROADMAP edits land or explicit skip rationale is documented; failed when documentation is known to be out of date; skipped when no documentation scope applied.version: passed when plugin manifest version bumps are verified (bump-version.ps1 completed or version is already correct); failed when manifests are out of sync; skipped when no version-bump scope applied.releaseTag: passed when the release tag exists on the merged commit or explicit skip rationale exists; failed when the tag was expected but is absent; skipped when no release-tag scope applied.
Code-Conductor passes this hashtable to Build-PostPrCreditRow -ChecklistOutcomes @{...} to emit the post-pr credit row into the PR-body pipeline-metrics block.
Gotchas
| Trigger | Gotcha | Fix |
|---|
git status shows .copilot-tracking/ files as untracked | These are gitignored local scaffolding, not team artifacts | Never git add them; use GitHub issues and Documents/Design/ for durable records |
Updating an existing file using mcp_github_create_or_update_file | Tool replaces the entire file; partial content silently truncates to just the new text | Use replace_string_in_file + git commit + git push for existing files |
Restoring a file from git history using Set-Content or Out-File | PowerShell may add BOM or CRLF causing noisy diffs | Use git restore --source=<sha> <file> instead |
Looking for the Documents/Design/ file before the PR is merged | The file is created by Code-Conductor in the PR diff, not in the repo pre-merge | Check the PR diff, not the repo, for the design doc |
Version bump using mcp_github_create_or_update_file with partial content | Tool replaces entire file; version bump deletes all other content | Use pwsh .github/scripts/bump-version.ps1 -Version X.Y.Z or replace_string_in_file |
| "PR merged — done" without running the cleanup checklist | Stale branches persist; related issues stay open; version history unclear | Run the full post-merge checklist (Steps 1–5) before declaring done |
| Skipping the pre-merge strategic assessment (Step 6 / SAR) | Missing the window to catch low-quality patterns before they set precedent | Complete Step 6 SAR before committing to merge on any >Medium impact PR |
| Archiving tracking files before committing documentation | PR created without updated design docs and changelog | Follow checklist order: documentation first, then archive |
Frame Ports Filled By This Skill
