teamcraft-jcg:complete-issue

---
name: teamcraft-jcg:complete-issue
description: Run pre-PR reviews (code health, security, deviation), push the branch, mark the Draft PR as ready for review, and update Jira issue status to "In Review". The final step before the PR goes to a teammate for review.
argument-hint: "[Jira issue key, e.g. PROJ-42]"
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - Task
  - AskUserQuestion
  - mcp__sooperset-mcp-atlassian__jira_get_issue
  - mcp__sooperset-mcp-atlassian__jira_transition_issue
  - mcp__sooperset-mcp-atlassian__jira_get_transitions
  - mcp__sooperset-mcp-atlassian__jira_update_issue
---

## Goal

Get the issue's changes ready for teammate review: code health and security reviewed, any significant deviations surfaced, branch pushed, Draft PR converted to ready, and Jira issue transitioned to "In Review". The developer decides what to fix before the PR goes out — this skill surfaces, advises, and executes their decisions.

## Hard Constraints

- The Jira issue key comes from `$ARGUMENTS`. Confirm the associated branch and Draft PR exist before proceeding.
- Run code health and security reviews in parallel — they are independent and both must complete before presenting findings.
- Present all review findings before making any changes. The developer decides what to fix, what to defer, and what to accept.
- If Critical or High security findings remain unaddressed, warn clearly before converting the PR to ready — but respect the developer's decision.
- **All Jira interactions go through the Atlassian MCP only.** Never use curl, REST calls, or GraphQL directly against Jira. If an operation cannot be performed via the MCP tools listed above, tell the developer it cannot be done and what they need to do manually.
- **All GitHub interactions go through the gh CLI only.** Never use curl or REST calls directly against GitHub. All PR operations (`gh pr view`, `gh pr list`, `gh pr edit`, `gh pr ready`, `gh pr create`, `gh run list`, `gh run view`) run via Bash.
- **Git push is the only operation performed via git CLI.** If `git push` fails due to auth, follow the guidance in `references/git-push-guidance.md` exactly — detect, stop, guide the developer, and wait.
- **`Closes #N` in the PR description does NOT close the Jira issue.** GitHub closing keywords close GitHub Issues, not Jira issues. Explicitly transition the Jira issue to "In Review" at the end of this skill. After the PR merges, post-merge must transition it to "Done" via `mcp__sooperset-mcp-atlassian__jira_transition_issue`.

## Identify the Work

Read `.teamcraft/project.md` to confirm the project. Find the branch for this issue (matching `*[ISSUE-KEY]-*` across all type prefixes) and the associated Draft PR in GitHub via `gh pr list --head [branch-name]`. Identify the base branch (the project's default branch).

Read the plan file at `.teamcraft/plans/[ISSUE-KEY].md` if it exists — it provides context for the deviation review.

## Run Reviews in Parallel

Launch two agents simultaneously using the Task tool:

**Code health review** — use the `teamcraft-jcg:code-health-reviewer` agent. Pass the base branch and the list of files changed since the base branch diverged.

**Security review** — use the `teamcraft-jcg:security-reviewer` agent. Pass the base branch and the list of files changed since the base branch diverged.

Wait for both to complete, then present all findings together.

## Run Deviation Review

If no plan file exists at `.teamcraft/plans/[ISSUE-KEY].md`, skip the deviation review entirely and tell the developer: "No plan file was found — the deviation review compares the implementation against the original plan, but no plan was persisted to disk. This happens when the plan was created before plan persistence was added, or when the session that created the plan ended before writing it. Skipping deviation review." Then proceed to the next section.

After the parallel reviews, use the `teamcraft-jcg:deviation-reviewer` agent. Pass the plan file path, the Jira issue key, and the base branch.

Present the deviation report. For each deviation the developer marks as significant, propose where the record should be updated: the Jira issue description (if the feature works differently), the tech decisions document in Confluence (if an architectural decision changed), or the PRD in Confluence (if scope shifted). This skill can update the Jira issue description directly via `mcp__sooperset-mcp-atlassian__jira_update_issue`. Confluence document updates must be handled by the developer separately — note the specific page URLs clearly so nothing is missed.

## Approve Fixes and Commit

For each fix the developer approves from the review findings, make the change, run the test suite to confirm nothing regressed, and commit with a message referencing the Jira issue key.

## Check Definition of Done

Before marking the PR ready, verify the issue's acceptance criteria against the actual implementation. Present the results — which criteria are met, which are partially met, and which are unmet with a clear explanation.

If any acceptance criteria are clearly unmet, warn the developer explicitly before proceeding. The developer decides whether to address them now or proceed to review — that decision is theirs to make, not yours to make for them.

## Check Pipeline Status

Use `gh run list --branch [branch-name]` via Bash to find any GitHub Actions workflow run on the feature branch. Use `gh run view [run-id]` for details if a run exists. Report the status clearly.

If the pipeline is failing, surface that clearly — the PR will likely be blocked from merge until it passes. The developer decides whether to address the failures before marking ready or to proceed with the pipeline in its current state.

If no workflow run has executed yet, note that.

## Assess In-Repository Documentation

Before marking ready, assess whether any in-repository documentation (README files, docs/ directory, inline documentation) is relevant to the changes being introduced and needs updating to remain accurate. The question is maintenance: does the existing documentation still accurately describe the system after these changes?

This is not an invitation to generate new documentation the team didn't ask for. The scope is limited to existing documentation that would be misleading or incomplete if left as-is.

Present your assessment to the developer. If any documentation updates are warranted, describe what needs changing and why, and wait for explicit confirmation before making any changes.

## Push and Mark Ready

Push the branch to origin. Then:
- Mark the Draft PR as ready: `gh pr ready [PR-number]` via Bash
- Update the PR description to include:
  - The Jira issue key and URL for traceability — note that this does NOT auto-close the Jira issue on merge; post-merge must handle that explicitly
  - Any deferred code health or security items as a "Suggested follow-ups" section
- See `references/example-pr-description.md` for what a well-formed PR description looks like

## Update Jira Issue Status

Fetch available transitions via `mcp__sooperset-mcp-atlassian__jira_get_transitions`. Transition the issue to "In Review" (or the closest equivalent status in the project's workflow) via `mcp__sooperset-mcp-atlassian__jira_transition_issue`. Never assume transition names — every Jira project has different workflow state names.

## Clean Up Plan Files

After the PR is marked ready and all reviews are complete, offer to clean up the plan file:

> "The plan file at `.teamcraft/plans/[ISSUE-KEY].md` is no longer needed — the implementation is complete and the PR is open for review. Want me to delete it?"

If yes, delete the file. If the `.teamcraft/plans/` directory is now empty, delete it too. If no, leave it.

## Done

Share the PR URL. The PR is now open for teammate review. Any approved changes are committed, deferred items are noted in the PR description, and the Jira issue reflects the current status.

**Reminder for later:** When the PR merges, run `post-merge` — it will explicitly transition the Jira issue to "Done" via `mcp__sooperset-mcp-atlassian__jira_transition_issue`. This cannot be automated by the PR description.