pr-lifecycle

name	pr-lifecycle
description	Manages the full PR lifecycle: creation, review comment handling, CI remediation, and user-approved merge
argument-hint	branch=feature/{feature-number}-{slug}
input	{"properties":{"branch":{"type":"string","description":"Feature branch to create PR for"},"title":{"type":"string","description":"PR title (optional, defaults to branch name)"}},"required":["branch"]}

PR Lifecycle Skill

Manage the branch-to-merged workflow for a feature or chore branch. This skill creates or updates the pull request, responds to review feedback, keeps CI healthy, and stops at the user merge gate unless the user explicitly approves the merge.

Purpose

Use this skill when implementation work is ready to move through pull request execution. It centralizes the PR control loop so higher-level agents can treat review, CI follow-up, and merge approval as one bounded workflow.

Agent-Intercom Communication

When the agent-intercom capability pack is installed, call ping at session start. If reachable, broadcast at every step. If unreachable, warn the operator that visibility is degraded and continue locally.

Event	Level	Message prefix
Session start	info	[PR-LIFECYCLE] Starting: branch={input.branch}
Branch pushed	info	[PR-LIFECYCLE] Branch pushed: {branch}
PR created	info	[PR-LIFECYCLE] PR created: {pr_url}
PR updated	info	[PR-LIFECYCLE] PR updated: {pr_url}
Feedback received	info	[PR-LIFECYCLE] Review feedback: {comment_count} comments
Fix applied	info	[PR-LIFECYCLE] Fix applied for: {comment_summary}
CI failure	warning	[PR-LIFECYCLE] CI failed — delegating to fix-ci
CI green	info	[PR-LIFECYCLE] CI passing
Ready for merge	success	[PR-LIFECYCLE] PR ready — awaiting user approval
Merged	success	[PR-LIFECYCLE] Merged: {pr_url}
Blocked	warning	[PR-LIFECYCLE] Blocked: {reason}

Inputs

• ${input:branch}: (Required) Branch name to ship.
• ${input:title}: (Optional) PR title override. When omitted, derive the title from the branch name or prepared PR description.

Workflow

Step 1: Prepare the branch

1. Confirm the branch exists locally and is ready to push.
2. Gather or generate the PR title and body before calling GitHub tooling.
3. Push the branch if it is not already available on the remote.

Step 2: Create or update the pull request

1. Use the GitHub CLI (gh pr create or gh pr edit) to create or refresh the pull request.
2. Capture the PR URL, branch, and base branch as the active context.
3. Reuse an existing PR when the branch already has one instead of creating duplicates.

Step 2b: Request automated review

When the repository is hosted on GitHub, request Copilot Review immediately after PR creation or after pushing new commits:

1. Request review per .github/instructions/github-pr-automation.instructions.md §1.1.
2. Poll for review completion using the back-off cadence in §1.2.
3. Do not block on review — proceed to CI monitoring in parallel when possible, but complete the review poll before entering the fix cycle.

Step 3: Handle review feedback

1. Monitor PR review comments, especially automated review comments.
2. For GitHub-hosted repositories, follow the complete Copilot Review workflow in .github/instructions/github-pr-automation.instructions.md Part 1: categorize comments (§1.3), apply fixes (§1.4), reply to threads (§1.5), and resolve bot-authored threads via GraphQL (§1.6).
3. For non-GitHub repositories, apply bounded fixes directly when they are clearly actionable.
4. Re-run the relevant validation after each fix cycle.
5. Keep the PR description and review context aligned with the latest branch state.

Step 4: Handle CI failures

1. If CI fails, invoke the fix-ci skill with the active PR or branch context.
2. For GitHub-hosted repositories, ensure the fix-ci skill follows the CI polling protocol in .github/instructions/github-pr-automation.instructions.md Part 2 for status monitoring, failure extraction, and fix-push-poll loops.
3. Let fix-ci own the remediation loop for failing checks and unresolved review comments.
4. Return to PR monitoring once CI and review status are clean again.

Step 4b: Re-request review after fixes

When fixes were pushed (from either review or CI remediation):

1. Re-request Copilot Review per .github/instructions/github-pr-automation.instructions.md §1.7.
2. Poll for the new review using the same back-off cadence.
3. Resolve any remaining bot-authored threads per §1.6.
4. Repeat until the review is clean or the review-fix cycle limit is reached.

Step 5: Merge approval gate

Step 5a: Pre-Merge Review Readiness Verification (NON-NEGOTIABLE)

Before presenting the PR as merge-ready, run the defense-in-depth Copilot review readiness verification defined in .github/instructions/github-pr-automation.instructions.md §1.9:

1. Execute the §1.9 readiness query (with full pagination of review threads).
2. Evaluate all three gate checks in order:
   • Check 1: No pending Copilot review request. If pending, wait per §1.2 back-off cadence.
   • Check 2: Latest Copilot review covers the current headRefOid. If stale, wait for a fresh review.
   • Check 3: Zero unresolved Copilot review threads. If any remain, halt and report.
3. If any check fails and the wait budget is exhausted, halt. Do not present the PR as merge-ready. Report the blocking condition to the operator.
4. If Check 3 fails with unresolved threads and the review-fix cycle budget (§1.8) has remaining capacity, loop back to Step 3 to address the unresolved comments. If the budget is exhausted, halt.
5. Surface human review threads, reviewDecision, and any CHANGES_REQUESTED reviews in the merge-readiness summary — these may independently block merge at the GitHub level.

Step 5b: Present merge readiness

1. When the §1.9 gate passes and checks are green, present the status to the user.
2. Wait for explicit user approval before any merge action.
3. Never auto-merge and never treat silence as approval.
4. If the user does not approve merge, leave the PR open and report the ready state.
5. Operator approval gate (P-014): After the §1.9 gate passes, wait for an explicit operator approval signal. Green CI is not approval. A passing §1.9 gate is not approval. Record P-014 (via P-005 telemetry) if merge is executed without an explicit approval signal.
6. Branch retention (NON-NEGOTIABLE): Remain on the current feature or chore branch while awaiting merge approval. Do NOT checkout {{DEFAULT_BRANCH}} or any other branch. The calling agent (Ship) depends on the branch context being preserved for post-merge work.

Step 5c: Last-Mile §1.9 Re-check Before Merge Execution

After receiving operator approval and before executing the merge:

1. Check whether any new commits have been pushed to the branch since the §1.9 gate ran. If yes, re-run §1.9 in full — the prior gate result is stale.
2. Check whether any new Copilot review threads have been opened since the §1.9 gate ran (query reviewThreads filtered to isResolved == false and author.login == "copilot-pull-request-reviewer"). If any new unresolved threads exist, halt and report — do not proceed to merge.
3. If the branch HEAD and review state are unchanged from the §1.9 gate run, log P-014 LAST-MILE CHECK PASSED: branch unchanged, no new unresolved threads.
4. Execute the merge only after this check passes.

This last-mile check closes the race window between approval receipt and merge execution. It is a lightweight incremental query (not a full §1.9 re-run) when the branch has not changed.

Step 6: Post-merge cleanup

After a user-approved merge:

1. Report the merge result and resulting default-branch state.
2. Do NOT checkout {{DEFAULT_BRANCH}} and start working on it. Post-merge closure work belongs on a dedicated post-merge/ branch created by the Ship agent. This skill's responsibility ends at reporting the merge result.
3. Delete the feature branch only when that cleanup is requested or already part of the chosen PR flow.
4. Summarize any follow-up items, release notes, or residual risks that remain after merge.

Completion Criteria

The skill is complete only when one of these outcomes is explicit:

• the PR is open and ready, waiting on user merge approval
• the PR feedback and CI loop is blocked with a clear reason
• the PR was merged after explicit user approval

Stop Conditions

Counter	Limit	Action
Fix-CI delegation cycles	5	Halt, leave PR for manual intervention
Review-fix cycles	3	Accept remaining as backlog follow-ups

Model Routing

This skill operates at Tier 2 (Standard) — PR creation and follow-up is routine coordination.