teamcraft:merge-issue

---
name: teamcraft:merge-issue
description: Finalize and merge an approved (or solo-flow) PR. Verifies approval and CI status, marks the work item as done on the branch, commits, then merges. This is the skill that actually completes the work. Use when the user says "merge this issue", "ship this", "PR is approved, merge it", "finalize this issue", or "the review is done, let's merge".
argument-hint: "[work item ID — e.g. feat-notification-prefs, bug-timezone-display]"
disable-model-invocation: false
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - AskUserQuestion
---

## Why This Skill Exists

The work item's `status: done` must be written on the branch before merge, not on main after merge. Once a PR merges, the branch is dead — nothing else can be committed to it. So the final commit on the branch updates the work item to `done`, and then we merge. Main inherits the correct state via the merge itself.

This is why `merge-issue` is the one skill that actually completes the work. `validate-issue` submits. `address-review-issue` iterates. `merge-issue` ships. No other skill marks a work item `done`.

## Verify the PR Is Ready to Merge

Identify the work item (from `$ARGUMENTS`, or from `.teamcraft/work/INDEX.md` looking for an `in-review` item on the current branch) and the PR associated with the branch.

**Check all of these before proceeding:**

1. **The PR exists and is ready for review** — not a Draft.
2. **CI has passed.** Use whatever tools are available to check CI status. If CI has not completed or has failed, stop. Do not merge on failing CI under any circumstances.
3. **Approval status:**
   - If this is a team-review flow, verify the PR has the required approvals per the team's process.
   - If this is a solo flow (the developer chose "going solo" during `validate-issue`, or confirms it now), approval is not required.
4. **The branch is up to date** — if the target branch (e.g., `main`) has moved since this branch last updated, flag this so the developer can decide whether to rebase/merge before proceeding. Some teams require branches to be current; others don't.

If any check fails, stop. Tell the developer exactly what's blocking the merge and why.

## Confirm with the Developer

Before taking destructive action, confirm: **"All checks pass. Ready to merge this to main? This will: update the work item to done, commit that change on the branch, and merge the PR."** Wait for explicit confirmation.

If the developer isn't sure (e.g., wants to check one more thing), stop and let them run the skill again when ready.

## Finalize the Work Item on the Branch

On the current branch (NOT on main):

1. Update the work item frontmatter:
   - `status: done`
   - `completed: YYYY-MM-DD` (today's date)
2. Update `.teamcraft/work/INDEX.md`:
   - Change the item's status column to `done`
3. Commit both files with the work item ID in the commit message. Example: `chore(feat-notification-prefs): mark work item as done`
4. Push the commit to the remote branch.

This is the final commit on the branch before the merge. Main will inherit this state when the merge completes.

## Merge the PR

**Before merging**, consult the team's captured operating conventions for the prescribed merge strategy — squash, merge commit, or rebase. Locate the conventions via the repo's README or the standard documentation locations; don't assume a specific path. If no strategy is documented anywhere, ask the developer.

Execute the merge using the prescribed strategy. Confirm the merge succeeded by checking the PR status after the operation.

## Cleanup

After the merge succeeds:

1. Check out the default branch (typically `main`) locally.
2. Pull to get the merged state.
3. Optionally delete the local work branch — ask the developer first. Some teams keep branches briefly for reference.

## When the Skill Is Complete

The skill is complete when ALL of the following are true:

1. The PR was verified as approved (or solo-flow confirmed) with CI passing before merging
2. The work item was updated to `status: done` and `completed: YYYY-MM-DD` on the branch
3. `.teamcraft/work/INDEX.md` was updated to reflect the new status
4. The final commit was pushed to the branch
5. The PR was merged successfully
6. The developer has confirmed the merge completed as expected

Main now reflects the correct final state: the work item is `done`, the `completed` date is accurate, and the INDEX.md is current. No post-merge operations needed.

Report the outcome:
- Work item ID and title
- Completed date
- Merged PR number and URL
- Any follow-up items the developer might want (e.g., deferred work items from earlier reviews)

Do NOT start another work item here. The developer decides what's next — `/pick-next-issue` is their natural next move if they want to keep going.