issue-hygiene

name	issue-hygiene
description	Keep GitHub issues + their checklists / comments in sync with PR landings as work progresses (live tracking) AND run periodic sweeps for drift. Use AS PRs MERGE to tick checklist boxes and post short progress comments — don't batch this until Friday. Run a fuller sweep on Fridays, after a merge cluster, or when user types /issue-hygiene. Tracker is danbri/factoidal#198; migration epic is

Issue tracker hygiene

The repo's issue tracker drifts: PRs merge that resolve open issues but forget to link back; assumptions in older issues become invalid silently; codename-violator items continue to track work that's now blocked-on-or- covered-by the recovery plan. This skill keeps the tracker honest.

The standing home for findings + tech-debt items is #198 (Issue tracker hygiene). The migration tracker is #200.

There are two postures for this skill:

• Live tracking — update issues as work lands, in the same session the work happens. This is the default posture during active dev.
• Periodic sweep — Friday afternoon, after a merge cluster, or when explicitly invoked. Catches everything that the live-tracking posture missed.

Live tracking — during active work

The migration epic (#200) and any "tracker" issue (e.g. #198, profile- specific epics) carry checklists. As work lands on claude/main, those checklists fall out of date the moment the PR merges.

Rule of thumb: every time a PR merges that ticks a checkbox, post a one-line update. Every time scores change, refresh the affected issues / docs in the same session.

Triggers

• PR merged that resolves a checkbox in a tracker issue. Tick the checkbox in the issue body; post a one-line comment naming the PR.
• PR merged that flips a W3C test suite score. Update #200's "Score snapshot" comment / checklist with the new pass/fail count.
• Agent reports back with a useful diagnosis (even if no PR lands). Post the diagnosis as a comment on the relevant issue so the next agent doesn't re-investigate.
• Merge cluster ends (≥3 PRs merged in <1 hour, then a quiet period). Post a single status update on #200 summarising what landed + new score snapshot.

What to post (live tracking)

Short. Single sentence + PR link. Optional 1-line score delta. Examples:

#229 merged: prp-key (HasKey) lands. Profile-RL OWL 2 RL: 15 → 16 pass.

#230 merged: harness fix for imports-011. Profile-RL OWL 2 RL: 16 → 17 pass (combined with #229).

Cluster K diagnosis update: agent confirmed Parser.RDFXML.fst is §6.1.4-correct; the fix moves harness-side. See #227 for the decision-gate doc.

For the migration epic specifically: tick the relevant checkbox in the issue body using the update_issue API. Don't add the comment AND tick the box in two separate API calls — do both.

What NOT to post (live tracking)

• Long progress essays — those go in design docs.
• "Working on it" updates with no concrete change.
• Sycophantic adjectives — see the markdown-style skill.
• A new comment per merge in a 5-PR cluster — bundle into one.

When to invoke (full sweep)

• Friday afternoon — full-sweep hygiene pass.
• After a merge cluster (≥3 PRs merged in <1 hour) — quick pass to link any newly-resolved issues.
• When opening a PR that references an issue — cross-link in both directions; don't auto-close.
• When merging a PR that closes an issue via "Closes #X" — verify the linkage rendered correctly + the auto-closure happened.
• User invokes /issue-hygiene or asks to "review issues".

Auth + repo

• gh is authenticated as the user; ensure with gh auth status.
• Always pass --repo danbri/factoidal (local-proxy git remote).

Sweep flow

1. Pull the inputs

gh issue list --repo danbri/factoidal --state open --limit 200 \
  --json number,title,body,labels,createdAt,updatedAt \
  > /tmp/issues-open.json

gh pr list --repo danbri/factoidal --state merged --limit 100 \
  --json number,title,body,mergedAt,headRefName \
  > /tmp/prs-merged-recent.json

2. For each open issue, decide

Outcome	Action
Close + link	A merged PR / current claude/main state resolves the issue. Post one-sentence comment naming the PR; gh issue close <n>.
Comment + leave open	Partial progress; or the issue's broader framing isn't fully resolved. Post a status comment cross-linking the relevant PRs / design docs.
Leave alone	Issue is current and accurate. Move on.
Mark duplicate	Another open issue covers the same ground. Comment, close as duplicate, link to the survivor.
Mark stale (rare)	Pure exploration that's been answered elsewhere or is no longer relevant. Comment + close with not-planned or wontfix.

3. Cross-reference for the codename-violator cluster

Issues #106 + #107–#116 (and any with Yod6 / Tet3 / Lamed3 / Mem5 / Pe5 / Bet7 / Tav5 / Heth3 in title or body) are part of the recovery plan. Don't close them based on PRs alone — they close when the relevant codename is retired in claude/main AND the boundary audit shows the corresponding VIOLATION-SEM row gone.

The migration epic (#200) has a checkbox per codename. Tick the checkbox first; close the issue only when the box is ticked AND the PR that retired the violator is merged.

4. Standing tech-debt sweeps

The hygiene tracker (#198) carries a checklist of small tech-debt items that don't warrant their own issue. Run through them on each Friday sweep:

• failwith "Not yet implemented" straggler scan in extracted .ml.
• Orphan experimental_ocaml_glue/*.sh patches with no matching assume val.
• Stale docs/designissues/ plan docs (>90 days, status pending).
• Retired-codename entries in docs/code-name-glossary.md that should be marked historical.
• bin/<platform>/ binary staleness vs ocaml-output/*.ml mtimes.

If any sweep produces a real chunk of work, file a dedicated issue and link from #198.

Reporting template

End every sweep with a comment on #198 in this shape:

## Hygiene sweep <YYYY-MM-DD HH:MM UTC>

- Open at start: N
- Closed: K — list of #N → resolving PR
- Updated: M — short description of each
- Left alone: P
- New issues filed from sweep: Q (link each)
- Tech-debt checklist progress: ticked X of Y

Use the markdown-style skill for the comment body — no ** adjacent to issue link ] chars.

Cautions

• Never bulk-close based on age. Old isn't dead.
• Never close codename-violator issues without the migration-epic box ticked AND a PR link AND the audit confirming retirement.
• Never reorder priority labels — that's the user's call.
• Don't post wall-of-text comments. One sentence + the resolving PR is enough. Multi-paragraph belongs in a design doc, not an issue.
• Don't open new issues during a sweep unless the finding is real and stand-alone work; otherwise note it on #198.

What this skill does NOT do

• Doesn't decide priority; doesn't reorder a backlog.
• Doesn't merge PRs.
• Doesn't close issues marked with the user's hold labels (e.g. discussion, decision-pending).
• Doesn't create labels — those are the user's curation.

Cross-references

• github-and-prs skill — gh CLI mechanics, branch/PR conventions.
• markdown-style skill — for hygiene-comment formatting.
• Issue #198 — the hygiene tracker (this skill's home).
• Issue #200 — F* migration epic; cross-tick from here.
• docs/designissues/2026-05-07-query-planning-fstar-recovery.md — recovery plan; inputs to violator-issue decisions.
• docs/designissues/fstar-ocaml-boundary-audit.md — current classification; the source of truth for "is the violator retired".