---
name: tracking-issue-closeout
description:
  Finalize and close plan-tracking GitHub issues after issue-backed execution is complete and the user or project policy has approved
  closure.
---

# Tracking Issue Closeout

## Contract

Prereqs:

- Run inside the target GitHub-backed git repository, or pass `--repo <owner/repo>`.
- `gh` is available on `PATH`, and `gh auth status` succeeds for live mode.
- `python3` is available on `PATH`.
- The target issue was created by `plan-tracking-issue` or has equivalent source and plan snapshot comments.
- Issue-backed execution has already completed through `execute-from-tracking-issue`.
- The user explicitly approved issue closure, or project policy explicitly says this tracking issue closes after successful execution.

Inputs:

- GitHub issue number or URL via `--issue <number-or-url>`.
- Optional repository override via `--repo <owner/repo>`.
- Required close authorization via `--review-approved` or `--review-comment-url <url>`.
- Optional offline fixture via `--issue-json <path>` for audit/render dry runs without live GitHub reads.
- Optional output paths for rendered dashboard, closeout comment, and JSON report.
- Optional `--skip-pr-checks` only when PR merge state has already been verified externally and recorded in the issue.
- Optional `--repair-closed` for an already closed issue whose final dashboard drifted after execution. This mode is explicit and never
  closes the issue again.
- Optional `--finalize-closed` with `--repair-closed` to append one missing `<!-- tracking-issue-closeout:v1 -->` comment for an already
  closed, otherwise complete issue. Existing closeout markers are never duplicated.

Outputs:

- Final issue body dashboard with status, durable record links, validation summary, linked PRs, blockers, and next action.
- Append-only `<!-- tracking-issue-closeout:v1 -->` closeout comment summarizing checks, outcome, and approval basis.
- Closed GitHub issue with reason `completed` in live mode.
- In `--repair-closed` mode, updated final dashboard body and JSON report only by default.
- In `--repair-closed --finalize-closed` mode, one missing closeout marker may be appended before the dashboard repair; existing markers are
  left untouched.
- Machine-readable JSON closeout report when `--report-out <path>` is supplied.
- Concise stdout summary with issue URL, close status, rendered files, and check result.

Exit codes:

- `0`: success
- `1`: readiness, validation, GitHub mutation, or close gate failure
- `2`: usage error

Failure modes:

- Target issue is unreadable, already closed without `--repair-closed`, open while `--repair-closed` is selected, or not associated with the
  selected repository.
- Missing source snapshot, plan snapshot, execution-state comment, or completed session/final summary.
- Latest execution state is not `complete`, lacks the canonical task ledger, or contains task rows not marked `done` or `deferred`.
- Closure is not explicitly approved by the user or by supplied project-policy evidence.
- Validation evidence is absent from execution comments.
- Linked PRs are not merged when live PR checks are enabled.
- Body/comment mutation or issue close fails, leaving the issue open with the failing command reported.

## Scripts (only entrypoints)

- `$AGENT_HOME/skills/workflows/issue/tracking-issue-closeout/scripts/tracking-issue-closeout.sh`

## Workflow

1. Read the tracking issue:
   - Live mode: `gh issue view <issue> --json number,title,state,body,comments,labels,url`.
   - Fixture mode: load `--issue-json <path>` and require `--dry-run`.
2. Verify closeout readiness:
   - `<!-- plan-tracking-issue:snapshot:v1 kind=source -->` exists.
   - `<!-- plan-tracking-issue:snapshot:v1 kind=plan -->` exists.
   - `<!-- execute-from-tracking-issue:state:v1 -->` exists.
   - The execution-state marker and status fields are outside any collapsed `<details>` block when the state comment uses the default
     collapsed-ledger format.
   - Latest execution state has `Status: complete`.
   - Every latest execution-state task row is `done` or explicitly `deferred`.
   - At least one `<!-- execute-from-tracking-issue:session:v1 -->` comment exists and the latest session indicates completion.
   - Validation evidence exists in a validation comment or execution session.
   - The user supplied `--review-approved` or `--review-comment-url`.
   - Explicit linked PR references are merged unless `--skip-pr-checks` is used. The parser accepts `PR #<number>`,
     `pull request #<number>`, and GitHub `/pull/<number>` links; generic issue, decision, task, and bare `#<number>` references are not PR
     evidence.
3. Render final issue body as a compact current dashboard. Do not copy the full source, plan, or sprint logs into the body; link the
   durable snapshot/session comments instead.
4. Render one append-only closeout comment with marker `<!-- tracking-issue-closeout:v1 -->`.
5. In dry-run mode, write requested body/comment/report artifacts and print the planned actions without mutating GitHub.
6. In `--repair-closed` mode:
   - Require the issue to already be closed and all other closeout gates to pass.
   - Render and update only the final dashboard body.
   - Do not post a new closeout comment unless `--finalize-closed` is also supplied and no closeout marker exists.
   - With `--finalize-closed`, append exactly one missing closeout marker before repairing the dashboard; if a marker already exists, do not
     duplicate it.
   - Do not call `gh issue close`.
   - Report `mode=repair-closed` / `repair_only=true`, or `mode=repair-closed-finalize` / `finalized_closed_issue=true`, in stdout and JSON.
7. In normal live mode:
   - Post the closeout comment first.
   - Update the issue body dashboard, including the closeout comment URL when available.
   - Close the issue with reason `completed`.
8. Report the final state, issue URL, linked PRs, validation summary, and any accepted caveats.

## Relationship To Nearby Skills

- `plan-tracking-issue`: creates the tracking issue and source/plan snapshot comments.
- `execute-from-tracking-issue`: executes the issue-backed plan and appends state/session/validation comments; it does not close by default.
  Execution-state creation remains owned by `execute-from-tracking-issue`, not by closeout or repair mode.
- `issue-follow-up`: use for generic GitHub issue follow-up that is not tied to plan snapshot markers.
- `issue-lifecycle`: lower-level issue mutation helper for generic open/update/comment/close operations.
- `dispatch-issue-closeout`: use for heavyweight dispatch or plan-issue runtimes with task-lane close gates, approvals, and merged PR checks.
