teamcraft-glgd:complete-issue

---
name: teamcraft-glgd:complete-issue
description: Run pre-MR reviews (code health, security, deviation), push the branch, mark the Draft MR as ready for review, and update issue labels. The final step before the MR goes to a teammate for review.
argument-hint: "[issue IID]"
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - Task
  - AskUserQuestion
  - mcp__gitlab__create_merge_request
  - mcp__gitlab__get_merge_request
  - mcp__gitlab__list_merge_requests
  - mcp__gitlab__update_merge_request
  - mcp__gitlab__get_issue
  - mcp__gitlab__update_issue
  - mcp__gitlab__list_labels
  - mcp__gitlab__list_projects
  - mcp__gitlab__list_pipelines
  - mcp__gitlab__get_pipeline
---

## Goal

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

## Hard Constraints

- The issue IID comes from `$ARGUMENTS`. Confirm the associated branch and Draft MR 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 MR to ready — but respect the developer's decision.
- When updating labels (adding "In Review", removing "In Progress"), fetch current labels first, merge the change, then update. Never replace all labels.
- **All GitLab interactions go through the MCP server only.** Never use curl, the GitLab CLI, REST calls, or GraphQL directly. 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 — do not attempt workarounds.
- **Git push is the only operation performed via git CLI.** Everything else touching GitLab goes through MCP. If `git push` fails due to auth, follow the guidance in `references/git-push-guidance.md` exactly — detect, stop, guide the developer, and wait.

## Identify the Work

Read `.teamcraft/project.md` to confirm the project. Find the branch for this issue (matching `*[IID]-*` across all type prefixes) and the associated Draft MR in GitLab. Identify the base branch (the project's default branch).

Read the plan file at `.teamcraft/plans/[IID].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-glgd:code-health-reviewer` agent. Pass the base branch and the list of files changed since the base branch diverged.

**Security review** — use the `teamcraft-glgd: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/[IID].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-glgd:deviation-reviewer` agent. Pass the plan file path, the issue IID, and the base branch.

Present the deviation report. For each deviation the developer marks as significant, propose where the record should be updated: the GitLab issue description (if the feature works differently), the tech decisions document in Drive (if an architectural decision changed), or the PRD in Drive (if scope shifted). This skill can update the GitLab issue description directly. Drive document updates must be handled by the developer separately — note them 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 IID.

## Check Definition of Done

Before marking the MR 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 `mcp__gitlab__list_pipelines` to find any pipeline running or completed on the feature branch. Use `mcp__gitlab__get_pipeline` for details if a pipeline exists. Report the status clearly.

If the pipeline is failing, surface that clearly — the MR 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 pipeline has run 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 MR as ready (remove draft status via `draft: false`)
- Update the MR description to include:
  - `Closes #[IID]` — this is mandatory. GitLab uses this to automatically close the issue when the MR merges to the default branch. Without it, the issue stays open after merge.
  - Any deferred code health or security items as a "Suggested follow-ups" section
- See `references/example-mr-description.md` for what a well-formed MR description looks like

## Update Issue Labels

Fetch current issue labels, remove "In Progress", add "In Review", then update.

## Clean Up Plan Files

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

> "The plan file at `.teamcraft/plans/[IID].md` is no longer needed — the implementation is complete and the MR 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 MR URL. The MR is now open for teammate review. Any approved changes are committed, deferred items are noted in the MR description, and the issue reflects the current status.