feat: /issue_cleanup — GitHub issue-tracker reconciliation door

[Jammy2211]

Overview

PyAutoLabs has no door that reconciles the GitHub issue trackers. /repo_cleanup sweeps git debris and stops there, /community handles external issues awaiting a reply, and /create_issue / /update_issue are single-issue primitives — nothing owns "audit the open issues, find the dead ones, close them". The trackers had drifted to 82 open issues across 18 repos, of which 35 were closable.

An ad-hoc sweep on 2026-07-28 cleared those 35 (29 shipped-but-still-open, 6 obsolete 2018–2019 PyAutoCTI) leaving 47. This issue makes that reconciliation a reusable, human-gated skill so the tracker never silently drifts to 80+ again.

Plan

• Add PyAutoBrain/skills/issue_cleanup/ as a standalone execution door modelled on /repo_cleanup: audit → bucketed dashboard → per-bucket human confirmation → execute → recap.
• Encode the four ways a naive "has a PyAutoMind record → close it" rule was proven wrong, above all the record header-key taxonomy.
• Require two independent evidence legs (record header + merged PR) before any issue is even proposed for closing.
• Wire it into COMMANDS.md, bin/install.sh, and the /wake_up digest — audit auto-runs read-only, every close stays human-gated.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary, only)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoBrain	main	M skills/WORKFLOW.md (concurrent, unrelated)

Suggested branch: feature/issue-cleanup
Worktree: ~/Code/PyAutoLabs-wt/issue-cleanup/

What the ad-hoc sweep established

The classifier needed four corrections, each found by verification rather than inspection. These are the skill's core requirements:

1. Body mentions are not claims. Grepping record files for an issue URL over-matches — complete/2026/05/many-vis-prep-dft.md discusses PyAutoArray#326 in prose while its own - issue: header reads (CI-triage cluster G, no GitHub issue). Only the header line is evidence.

2. The header key carries the meaning — the load-bearing rule. Across 800 records: issue: (630 uses) means this record completes that issue. But followup-issue:, follow-up-issue:, library-followup-issue:, parent-issue:, upstream-issues-filed: and plan: (13 uses) mean the opposite — the record spawned that issue and it is legitimately open. A loose *issue*: match would close live follow-ups.

3. Annotations override. Records mark deliberate exceptions inline: (open — findings census stays as reference), (STAYS OPEN — real finding + resumable fit), (STAYS OPEN for the optional model-parity fit leg), (both stay OPEN for parked design work only). Any open token means hands off — and these appear on plan: lines, not just issue: lines.

4. A record in complete/ does not mean the work completed. ep-hierarchical-scale-collapse.md carries Status: issued — it filed PyAutoFit#1405 and reported two defects on it. The record is complete; the issue is a live bug. Read the status field, not the directory.

Corroborating: PyAutoReduce#8's record already said (CLOSED) while GitHub had it open — closes do silently fail to land.

Buckets

Bucket	Definition	Action
A shipped	completing header key + no open annotation + merged PR	closable, on confirmation
B weak evidence	record exists, an evidence leg fails	report only
C deliberately open	annotation says so	never touch
D in flight	present in active.md / parked.md	never touch
E external	author is not the maintainer	route to /community
F unreconciled	no record at all	the real backlog; sub-split by age

The PR leg needs both paths: the GitHub timeline cross-reference and a PR number named in the record body — 12 of the 29 closable issues had only the latter, so timeline alone under-reports.

Obsolescence needs a real check, not an age threshold

The 8 oldest issues split on evidence, not age. The 6 PyAutoCTI ones (2693–2785 days) named FrameGeometry, CIFrame, CIData, ci_data_analysis, ci_pattern, phase.py/pipeline — grep of autocti/ returns zero for every one (the CTI resurrection removed that surface), so they closed not_planned. PyAutoHands#16 (test against pre-release deps) and #17 (fail build if RTD docs fail) are the same vintage (~1337 days) but were left open — no --pre workflow and no RTD gating exist in PyAutoHands/.github/workflows/, so they remain valid unimplemented asks. The skill must probe whether the named API/infra still exists.

Implementation Steps

1. skills/issue_cleanup/issue_cleanup.md — canonical command body (the <verb>.md convention /hygiene and /wake_up follow): scope repos → fetch open issues (select(.pull_request == null)) → parse record headers → classify A–F → dashboard → per-bucket confirm → execute → recap.
2. skills/issue_cleanup/SKILL.md — thin discovery wrapper, frontmatter name: issue-cleanup (hyphenated for Codex).
3. skills/issue_cleanup/reference.md — header taxonomy table, bucket definitions, dashboard layout, per-bucket execution.
4. skills/COMMANDS.md — add /issue_cleanup as a maintenance/execution door (/repo_cleanup is currently absent from this file too; add alongside).
5. skills/wake_up/wake_up.md — add a read-only reconciliation count to the digest.

Mechanics

• gh issue close is broken in this environment. Comment first, then gh api -X PATCH repos/<owner>/<repo>/issues/<n> -f state=closed -f state_reason=<completed|not_planned>.
• completed for bucket A; not_planned for obsolete.
• Every close leaves a comment naming its evidence (record path + PR) so the decision is auditable and reversible.
• Recognise bot-authored self-refreshing issues ([url-check], [heart-health]) and exclude them from staleness ranking.

Testing

Re-run the audit half against today's post-sweep state and assert it reproduces the known-good classification: 47 open, zero bucket-A candidates (all closed today), the 5 annotated C issues held back, and the 6 follow-up-key issues correctly not proposed. A real regression bar, not a smoke check.

Install caveat

bin/install.sh run from a worktree repoints ~/.claude at that worktree. Create the two symlinks by hand; leave install.sh to run from the main checkout post-merge.

Key Files

• PyAutoBrain/skills/issue_cleanup/issue_cleanup.md — command body (new)
• PyAutoBrain/skills/issue_cleanup/SKILL.md — discovery wrapper (new)
• PyAutoBrain/skills/issue_cleanup/reference.md — taxonomy + execution detail (new)
• PyAutoBrain/skills/COMMANDS.md — routing entry
• PyAutoBrain/skills/wake_up/wake_up.md — digest line

Notes on classification

Brain's Feature Agent returned large (score 9) → split-into-phases; overridden to single phase — one skill in one repo, with the design reasoning already settled by the sweep rather than pending discovery. Brain's cited risk ("public-API change may ripple downstream") is a false positive: a skill body is not an API. Heart is YELLOW (65) but its tick is stale (2026-07-27 17:18, citing 07-21 validation data) and none of its reasons gate a Brain skill addition.

Original Prompt

Click to expand starting prompt

See PyAutoMind/active/issue_cleanup_skill.md. The originating request was:

do we have a skill to do a github issue clean up?

Answered: no — /repo_cleanup covers git debris only, /community covers external issues, /create_issue and /update_issue are single-issue primitives. The user asked for an ad-hoc sweep first, then this skill.

[Jammy2211]

Shipped — PR #175 open.

The ad-hoc sweep that preceded the skill took the trackers 82 open → 47:

• 29 closed as completed (bucket A, two-leg verified: record header + merged PR)
• 6 closed as not_planned — PyAutoCTI Rename PyAutoAgent to PyAutoBrain #1–Modernise and re-home PyAuto workflow skills for PyAutoBrain #5, Add concise PyAutoBrain agent commands #16 (2693–2785 days), whose named API (FrameGeometry, CIFrame, CIData, ci_data_analysis, ci_pattern, phase.py/pipeline) greps zero in autocti/ after the CTI resurrection
• PyAutoHands#16/#17 left open — same ~1337-day vintage, but no --pre workflow and no RTD gating exist, so they are still-valid unimplemented asks

The skill then found two more failure modes its own regression bar caught, beyond the four from the sweep:

• Rule 1 was too loose. Matching any - word: line as a header re-admits prose: records use - notes: for long paragraphs that cite issue URLs freely. PyAutoGalaxy#417 is cited only there, so nothing claims it — it belongs in the backlog. Header keys are now a known-set allowlist.
• Rule 4 is new. A phase-scoped claim ((Phase 5 item 4), (Phase 5 F5 item)) completes a piece, not the issue. Four records each claim a Phase-5 item of PyAutoBrain#130; none establishes it is done. Scoped claims route to bucket B for a human.

The bar now pins the post-sweep state and both traps, and passes at the branch tip:

PASS open: 47   PASS A: 0   PASS B: 1   PASS C: 7
PASS spawn-held: 3   PASS D: 6   PASS E: 8   PASS F: 22
PASS PyAutoGalaxy#417 in F (notes-prose trap)
PASS PyAutoBrain#130 in B (umbrella trap)
PASS PyAutoHands#16/#17 in F

Per the approved mode: /wake_up runs the audit half only (read-only) and reports counts; every close stays behind this skill's per-bucket confirmation.

Remaining: merge, then run bin/install.sh from the canonical checkout to create the ~/.claude symlinks — deliberately not done from the worktree, which would repoint ~/.claude at it.

[Jammy2211]

Complete. Both PRs merged and installed on both harnesses.

• feat(skills): add /issue_cleanup — issue-tracker reconciliation door #175 — the skill (c97ad7f)
• chore(discovery): refresh committed .claude/.codex trees — issue_cleanup, community, eyes #176 — committed .claude/.codex discovery refresh (e74db88)

Installed for Claude and Codex:

Surface	Path
Claude skill	~/.claude/skills/issue_cleanup
Claude command	~/.claude/commands/issue_cleanup.md
Codex skill	~/.codex/skills/issue-cleanup

All resolve to the canonical checkout. The skill body now uses $verb notation with one explicit dual-notation line, and SKILL.md's name: stays hyphenated because Codex takes its skill name from it.

#176 fixed drift beyond this task. --write-project-discovery had not been re-run since the community and eyes doors landed, so those two and issue_cleanup were absent from the committed per-repo discovery tree — the tree that registers doors in cloud/web sessions, where the user-level symlinks do not travel. Three doors were invisible on web/Codex despite working locally. --check-project-discovery is clean again.

Install-script trap confirmed and recorded: an unknown flag falls through to a full install, and a full install run from a worktree repoints ~/.claude at that worktree. --write-project-discovery / --check-project-discovery short-circuit before the user-level install, so they are safe anywhere; the plain no-flag install must be run from the canonical checkout.

Post-merge cleanup done: worktree removed, both feature branches deleted local and remote, completion record at PyAutoMind/complete/2026/07/issue-cleanup.md, lifecycle check: OK.

Closing.