# Tracking Issue Closeout Repair Discussion Source

## Status

- Date: 2026-05-21
- Source: User discussion in the current Codex thread after live review of
  `sympoies/nils-cli` issue 401 and the `tracking-issue-closeout` skill.
- Intended next step: Create a provider tracking issue, then implement the
  sibling plan.
- Recommended plan:
  `docs/plans/tracking-issue-closeout-repair/tracking-issue-closeout-repair-plan.md`
- Recommended execution state:
  `docs/plans/tracking-issue-closeout-repair/tracking-issue-closeout-repair-execution-state.md`

## Purpose

Repair `tracking-issue-closeout` so future plan-tracking closeouts do not report
incorrect linked PRs and can recover the final issue dashboard when an issue was
closed before the closeout dashboard was updated.

## Confirmed Facts

- `sympoies/nils-cli` issue 401 was already closed when reviewed.
- Issue 401 had a latest complete `<!-- execute-from-tracking-issue:state:v1 -->`
  comment, session logs, validation comments, and merged sprint PRs.
- Issue 401 body still showed the old Sprint 1 `in-progress` dashboard until it
  was manually repaired.
- A dry run of `tracking-issue-closeout` against issue 401 found the complete
  execution-state and validation comments, but blocked because the issue state
  was `CLOSED`.
- The same dry run extracted linked PRs as `404, 9, 5, 405, 406, 407` because the
  parser treats any `#<number>` in execution comments as a PR reference.
- In issue 401, `#9` and `#5` came from decision references, not Plan 02 sprint
  PRs.
- The intended sprint PR set for issue 401 was PR 404, PR 405, PR 406, and PR 407.

## Decisions

1. Treat broad `#<number>` extraction as a bug. The closeout checker should only
   extract explicit PR references, such as `PR #404`, `pull request #404`, or
   GitHub `/pull/404` links.
2. Keep closed issue handling strict by default for normal live closeout, because
   a closeout should not accidentally duplicate comments or close an already
   closed issue.
3. Add an explicit repair or idempotent path for already closed issues so the
   dashboard body and report can be regenerated without posting a duplicate
   closeout comment or calling `gh issue close` again.
4. Preserve append-only execution comments. Repair mode should update the mutable
   issue body only unless the implementation explicitly documents and tests
   another safe behavior.

## Scope

- Tighten PR reference extraction in `tracking_issue_closeout.py`.
- Add tests that prove decision references like `Decision #9` are not treated as
  linked PRs.
- Add a closed-issue dashboard repair or idempotent mode to the closeout script.
- Update `tracking-issue-closeout` skill docs and issue workflow docs to describe
  the repair path and duplicate-comment guard.
- Validate the plan and the focused closeout tests before delivery.

## Non-Scope

- Do not change `plan-tracking-issue` snapshot creation.
- Do not change `execute-from-tracking-issue` execution-state ownership.
- Do not introduce dispatch issue closeout semantics into the lightweight
  plan-tracking closeout path.
- Do not reopen already closed issues as part of dashboard repair.
- Do not create a broad generic issue repair workflow.

## Requirements

- PR extraction must include explicit PR references:
  - `PR #404`
  - `pull request #404`
  - `https://github.com/owner/repo/pull/404`
  - `/pull/404`
- PR extraction must ignore generic issue, decision, task, and note references:
  - `Decision #9`
  - `Task #5`
  - `issue #401`
  - bare `#123` without PR wording.
- The script must expose an explicit closed-issue repair path or equivalent
  idempotent mode.
- Repair mode must render/update the final dashboard from existing markers while
  avoiding duplicate closeout comments and avoiding a second close operation.
- Normal live closeout must still require source snapshot, plan snapshot,
  execution state, completed session, validation evidence, approval, and merged
  linked PRs.
- The skill docs must make clear that execution-state creation remains the
  responsibility of `execute-from-tracking-issue`.
- Focused tests must cover PR parsing and closed-issue repair behavior.

## Acceptance Criteria

- `tracking-issue-closeout` dry-run/report no longer lists `Decision #9` or
  similar references as linked PRs.
- Closed issue repair mode can render and write a final dashboard from existing
  issue markers without requiring the issue to be open.
- Normal live closeout still blocks closed issues unless repair mode is selected.
- The rendered dashboard and closeout report distinguish normal closeout from
  repair-only behavior.
- Skill and issue workflow docs describe when to use repair mode.
- Focused tests for `tracking-issue-closeout` pass.
- `plan-tooling validate` passes for the sibling plan.
- `scripts/check.sh --all` passes before reporting implementation complete.

## Validation Plan

- `plan-tooling validate --file docs/plans/tracking-issue-closeout-repair/tracking-issue-closeout-repair-plan.md --format text --explain`
- `scripts/check.sh --tests -- -k tracking_issue_closeout`
- `scripts/check.sh --markdown`
- `scripts/check.sh --all`

## Risks And Guardrails

- Too-permissive closed issue repair could hide a bad closeout. Keep repair mode
  explicit and non-duplicating.
- Too-narrow PR parsing could miss valid closeout PR evidence. Include accepted
  PR shapes in tests.
- Updating issue bodies after close can be surprising. Limit repair mode to the
  mutable dashboard and report it clearly.
- Keep `tracking-issue-closeout` lightweight. Dispatch close gates remain owned
  by `dispatch-issue-closeout`.

## Execution

- Execution state recommendation:
  `docs/plans/tracking-issue-closeout-repair/tracking-issue-closeout-repair-execution-state.md`
- Status: ready for sibling plan execution.
- Next-task source:
  `docs/plans/tracking-issue-closeout-repair/tracking-issue-closeout-repair-plan.md`

## Retention Intent

This source document is a plan-created coordination artifact. It can be cleaned
up after the skill behavior, docs, tests, and provider issue all reflect the
same closeout repair contract.

## Open Questions

- None. The exact CLI flag name for repair mode can be chosen during
  implementation, but it must be explicit and documented.

## Read-First References

- `skills/workflows/issue/tracking-issue-closeout/SKILL.md`
- `skills/workflows/issue/tracking-issue-closeout/bin/tracking_issue_closeout.py`
- `skills/workflows/issue/tracking-issue-closeout/tests/test_workflows_issue_tracking_issue_closeout.py`
- `skills/workflows/issue/README.md`
- `skills/workflows/plan/plan-tracking-issue/SKILL.md`
