# Plan: Tracking Issue Closeout Repair

## Overview

Fix two closeout gaps discovered while repairing `sympoies/nils-cli` issue 401:
the linked-PR detector accepts unrelated `#<number>` references, and an issue
that was closed before the final dashboard mutation cannot be repaired through a
safe skill path.

## Read First

- Primary source: `docs/plans/tracking-issue-closeout-repair/tracking-issue-closeout-repair-discussion-source.md`
- Source type: discussion-to-implementation-doc
- Open questions carried into execution: none

## Execution

- Execution state: `docs/plans/tracking-issue-closeout-repair/tracking-issue-closeout-repair-execution-state.md`

## Scope

- In scope:
  - `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`
- Out of scope:
  - `plan-tracking-issue` snapshot creation behavior.
  - `execute-from-tracking-issue` execution-state ownership.
  - Dispatch issue closeout behavior.
  - Reopening already closed issues.
  - Commit, push, or PR delivery unless the user requests delivery.

## Assumptions

1. The repair can stay inside the existing Python helper and skill docs.
2. Closed issue repair should be explicit and should not post duplicate closeout
   comments.
3. Generic `#<number>` references are too ambiguous to use as PR evidence.
4. Focused tests are enough before full-gate validation because the behavior is
   localized to one workflow skill.

## Sprint 1: Fix Linked PR Extraction

**Goal**: Make linked PR detection precise enough for closeout gating without
mistaking decisions, tasks, or issues for PRs.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k tracking_issue_closeout`
  - `scripts/check.sh --markdown`
- Verify:
  - Explicit PR references are retained.
  - Generic `#<number>` references are ignored.
  - Closeout reports no longer contain unrelated decision numbers.

**PR grouping intent**: group
**Execution Profile**: serial

### Task 1.1: Add regression coverage for explicit PR references

- **Location**:
  - `skills/workflows/issue/tracking-issue-closeout/tests/test_workflows_issue_tracking_issue_closeout.py`
- **Description**: Extend the closeout tests so the fixture includes accepted PR
  reference forms and unrelated numeric references in the same execution
  comments.
- **Dependencies**:
  - none
- **Complexity**: 2
- **Acceptance criteria**:
  - Tests expect `PR #404`, `pull request #405`, and `/pull/406` to be extracted.
  - Tests expect `Decision #9`, `Task #5`, and `issue #401` to be ignored.
  - The test fails on the current broad `#<number>` parser.
- **Validation**:
  - `scripts/check.sh --tests -- -k tracking_issue_closeout`

### Task 1.2: Tighten the PR extraction parser

- **Location**:
  - `skills/workflows/issue/tracking-issue-closeout/bin/tracking_issue_closeout.py`
- **Description**: Replace broad `#<number>` parsing with explicit PR reference
  parsing while preserving order and de-duplication.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 3
- **Acceptance criteria**:
  - GitHub `/pull/<number>` links are extracted.
  - Text forms such as `PR #<number>` and `pull request #<number>` are extracted.
  - Bare `#<number>` and non-PR labels are ignored.
  - Existing report payload and dashboard rendering continue to receive the
    extracted PR list.
- **Validation**:
  - `scripts/check.sh --tests -- -k tracking_issue_closeout`

## Sprint 2: Add Closed Issue Dashboard Repair

**Goal**: Allow an already closed tracking issue to have its final dashboard
repaired from existing markers without duplicating closeout comments or closing
the issue again.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k tracking_issue_closeout`
  - `scripts/check.sh --markdown`
- Verify:
  - Normal closeout still blocks a closed issue.
  - Repair mode can render and write a final dashboard for a closed issue.
  - Repair mode is clearly reported as repair-only.

**PR grouping intent**: group
**Execution Profile**: serial

### Task 2.1: Add repair-mode tests for closed issues

- **Location**:
  - `skills/workflows/issue/tracking-issue-closeout/tests/test_workflows_issue_tracking_issue_closeout.py`
- **Description**: Add tests for an already closed issue with complete
  source/plan/state/session/validation markers and merged PR evidence.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Existing normal mode keeps failing closed issues.
  - Repair mode treats the same closed issue as renderable when all other gates
    pass.
  - Repair mode does not claim it posted a new closeout comment or closed the
    issue.
- **Validation**:
  - `scripts/check.sh --tests -- -k tracking_issue_closeout`

### Task 2.2: Implement explicit repair behavior

- **Location**:
  - `skills/workflows/issue/tracking-issue-closeout/bin/tracking_issue_closeout.py`
- **Description**: Add an explicit repair or idempotent mode that can render and
  update the issue body for closed issues while skipping duplicate closeout
  comment creation and second close calls.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 4
- **Acceptance criteria**:
  - The CLI exposes an explicit repair flag or equivalent idempotent control.
  - Normal live closeout keeps the closed-issue hard gate.
  - Repair mode updates or writes only the final dashboard and report.
  - Repair mode leaves append-only source, plan, session, validation, and
    closeout comments untouched.
  - The stdout summary and JSON report identify repair-only behavior.
- **Validation**:
  - `scripts/check.sh --tests -- -k tracking_issue_closeout`

### Task 2.3: Document the repair path

- **Location**:
  - `skills/workflows/issue/tracking-issue-closeout/SKILL.md`
  - `skills/workflows/issue/README.md`
- **Description**: Update workflow docs so future agents know when to use normal
  closeout versus closed-issue dashboard repair.
- **Dependencies**:
  - Task 2.2
- **Complexity**: 2
- **Acceptance criteria**:
  - `tracking-issue-closeout` docs state that execution state remains owned by
    `execute-from-tracking-issue`.
  - Docs describe the explicit repair mode and its non-duplicating behavior.
  - Issue workflow README preserves the normal skill sequence while noting that
    repair mode is for post-close dashboard drift.
  - Docs do not imply repair mode is a generic issue lifecycle tool.
- **Validation**:
  - `scripts/check.sh --markdown`

## Sprint 3: Validate The Closeout Contract

**Goal**: Validate the focused behavior, plan bundle, and full repository gate
before reporting the repair complete.
**Demo/Validation**:

- Command(s):
  - `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`
- Verify:
  - The plan remains executable.
  - Focused closeout tests pass.
  - Full repository validation passes before final delivery.

**PR grouping intent**: group
**Execution Profile**: serial

### Task 3.1: Run focused and full validation

- **Location**:
  - `docs/plans/tracking-issue-closeout-repair/tracking-issue-closeout-repair-plan.md`
  - `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`
- **Description**: Run plan validation, focused closeout tests, markdown checks,
  and the full repository gate; fix any drift that remains within this plan's
  scope.
- **Dependencies**:
  - Task 1.2
  - Task 2.3
- **Complexity**: 2
- **Acceptance criteria**:
  - Plan validation passes.
  - Focused closeout tests pass.
  - Markdown checks pass.
  - `scripts/check.sh --all` passes.
  - Any residual caveats are recorded in execution state before completion.
- **Validation**:
  - `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`
