Tracking Issue Closeout

Tracking Issue Closeout

Contract

Prereqs:

• Run inside the target GitHub-backed git repository, or pass --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 .
• Optional repository override via --repo .
• Required close authorization via --review-approved or --review-comment-url .
• Optional offline fixture via --issue-json 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 `` 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 `` 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 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 --json number,title,state,body,comments,labels,url.
• Fixture mode: load --issue-json and require --dry-run.

1. Verify closeout readiness:

• `` exists.
• `` exists.
• `` exists.
• The execution-state marker and status fields are outside any collapsed `` 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 `` 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 #,

pull request #, and GitHub /pull/ links; generic issue, decision, task, and bare # references are not PR evidence.

1. 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.

1. Render one append-only closeout comment with marker ``.
2. In dry-run mode, write requested body/comment/report artifacts and print the planned actions without mutating GitHub.
3. 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.

1. 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.

1. 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 timelines that are not tied to plan snapshot markers.
• Shared issue lifecycle tool (skills/workflows/issue/_shared/lib/manage_issue_lifecycle.sh): lower-level 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: graysurf
• Source: graysurf/agent-kit
• License: MIT

Install and usage instructions live in the source repository linked above.