issue-watch-closeout

name	issue-watch-closeout
description	Drive recurring GitHub issue work from shipped slices to final closeout or reusable closed-issue audits.

Issue-Watch Closeout

When to Use

• A shipped issue slice is ready to move into closeout
• An open issue already has shipped work and needs immediate closeout
• A recurring issue-watch run should validate or close an issue instead of opening new intake
• If the issue still needs repo-truth expansion or implementation, switch to .agents/skills/issue-contract-expansion/SKILL.md first

Canonical Surfaces

• GitHub issue thread comments via ./.git/helpers/gh-app
• AGENTS.md
• README.md
• handoff.md

Procedure

1. Read the full issue, latest comments, and latest shipped outcome before validating
2. Confirm there are no live active, prepared, or writing slices left for the issue
3. If shipped work is complete but closeout has not started, upsert a Marker: issue-watch-closeout note with Status: validation-ready and Slice: issue-closeout; treat that comment as the reusable closeout source comment
4. If the fixed ask still holds but the thread's broader follow-up scope never got its own issue, open or link that follow-up issue in the audit result instead of reopening the fixed issue
5. Refresh and recheck origin/main, then do one final read-only recheck against the issue ask on current main
6. If no blocker is open, update that same closeout source comment in place to Status: done, close the issue, and release the closeout slice
7. If the issue is already closed and needs a recurring audit, compare the latest reusable issue-watch-closed-audit note with the latest shipped change plus current main; if that note already covers the same-or-newer origin/main state and the issue thread has not changed since then, skip the thread write and keep any repeat no-op note only in a bounded repo-local operator surface when it changes handoff state
8. Otherwise, reuse or create exactly one Marker: issue-watch-closed-audit note and update it in place with the fresh recheck
9. Optional validated comments may still be left as extra signal, but they are never a closure gate

Guardrails

• Do not validate from stale thread context; reread latest comments first
• Do not validate from stale local state; refresh origin/main immediately before the final closeout recheck
• Do not close an issue if a validator found a real defect; reopen slicing with blocked, released, or a new mapped note instead
• If the concrete shipped ask is fixed but the thread has grown into a larger backlog, close the fixed issue and move the broader scope into a new follow-up issue instead of keeping one issue open forever
• If a closed issue is already correctly fixed, do not reopen it just to preserve backlog context; create or link the missing follow-up issue instead
• Reuse or update the existing source slice comment in place by default; append one fresh superseding closeout comment only when no editable source comment exists for that slice
• Do not append a second closeout note after validation-ready when the same editable closeout comment can be updated to done
• Use node tools/issue-watch-comment-upsert.mjs for reusable source-slice, closeout, and closed-audit comments instead of ad hoc append-only gh issue comment calls
• Do not append a new closed-state audit note on every recurring pass; keep one editable issue-watch-closed-audit comment per closed issue
• Do not edit that reusable closed-audit comment when neither origin/main nor the issue thread has advanced since the last audit; repeat no-change checks belong in repo-local handoff/operator state only when they change current state, not the issue thread
• Any issue-thread write should carry the current session's unique agent tag and Optacbook[bot] identity
• Keep comments business-readable and user-surface-focused

Validation

• The issue thread shows one fresh validation-ready note when closeout starts and that same note is edited in place to Status: done
• Closed issues keep one reusable issue-watch-closed-audit note that gets updated in place on later review runs
• A no-op closed-issue recheck leaves the issue thread unchanged
• Closed issues with broader leftover scope link a separate follow-up issue instead of being reopened for backlog tracking
• The closing run refreshes origin/main, rereads the shipped outcome, and updates the reusable closeout comment before closure
• A recurring closed-issue review updates one reusable issue-watch-closed-audit note in place instead of growing the thread with duplicate audits
• A recurring closed-issue review leaves the thread untouched when the last reusable closed-audit already covers the same current-main state
• The closing run uses the repo-local GitHub App helper/wrapper, not bare gh