git:20261019.84b981b to git:20261019.24fe48f

72 added, 25 removed. Audit A to A.

---

name: audit-issues

- description: "Audit a GitHub issue tracker: find open work hidden under closed issues, and give every open issue a checked verdict (done, duplicate, still real, or unsure with the check that would settle it). Use when asked to audit, clean up, triage, groom or sweep issues, or to say which open issues are still real. A script lists open issues under closed parents, issues closed with open work under them, duplicates of nothing and decisions closed without their answer; closes go through close-issues; scope decisions go to the owner."

- short_description: "Audit a tracker: hidden open work and a verdict per issue."

+ description: "Audit a GitHub issue tracker: group issues by the fix that would make them all disappear, rewrite workaround premises to the proper fix, close what is done, duplicated or out of date, and show the owner a short before-and-after page to approve before anything changes. Use when asked to audit, clean up, triage, groom, merge or sweep issues, or to say which open issues are still real. A script finds hidden open work, suggests likely slices of one cause and oversized milestones, checks the plan, and applies it only once approved; closes go through close-issues; scope decisions go to the owner."

+ short_description: "Audit a tracker: one issue per cause, approved before applied."

allow_implicit_invocation: true

---

# Audit issues

- A tracker drifts: work closes early with pieces still open, children stay open

- under a closed parent, and old issues describe code that has since changed. An

- audit finds that drift and says, for every open issue, whether it is still real.

- It never closes an issue itself: each close goes through the `close-issues`

- skill, and each scope decision goes to the owner.

+ A tracker drifts: one cause gets filed ten times from ten sightings, issues ask

+ for workarounds instead of the fix, work closes early with pieces still open,

+ and old issues describe code or releases that have since moved on. An audit

+ turns the tracker back into one issue per cause, each with its slices under it,

+ and shows the owner the result before anything changes.

+ The script is `python3 <folder of this SKILL.md>/scripts/audit_issues.py`

+ (below, `audit`). Its plan format is in

+ [references/plan-format.md](references/plan-format.md). Every close it makes

+ runs through the `close-issues` skill's script, so that skill must be installed

+ beside this one.

<what-to-do>

- 1. **Find the hidden work.** Run

- `python3 <folder of this SKILL.md>/scripts/audit_issues.py --repo OWNER/REPO`.

- It lists open issues under closed parents, issues closed as completed with

- open sub-issues or unticked lines, duplicates of nothing, decisions closed

- without a `## Decision`, and decision issues waiting on the owner. Fix each

- structural finding as it says and rerun until it exits 0.

- 2. **Give every open issue in scope one verdict**, from a check run now, never

- from the issue's age or text:

- - **Done:** you ran the check that proves it. Close it with `close-issues`.

- - **Duplicate:** of a named issue. Close it with `close-issues`.

+ 1. **Scan.** Run `audit scan --repo OWNER/REPO [--milestone TITLE]`. It lists

+ open work hidden under closed issues (fix each as it says and rerun until it

+ exits 0), milestones with more than 10 top-level issues, groups of issues

+ that look like slices of one cause, weaker one-signal leads, and issues

+ whose asked-for fix reads like a workaround. Its groups are leads; you

+ still read the issues before calling them one cause.

+ 2. **Split the work when there is a lot of it.** Past about 100 open issues,

+ write the full index with `audit index --repo R --out INDEX.tsv`, cut the

+ issues into batches of about 100 by area, and give each batch to its own

+ agent (where the client allows sub-agents, under its rules) together with

+ the whole index, so it can spot duplicates and causes outside its batch.

+ Each agent writes its verdicts into its own file, never a shared one.

+ 3. **Give every open issue in scope one verdict**, from a check run now, never

+ from the issue's age or wording:

+ - **Done:** you ran the check that proves it; the proof is a commit, a test

+ result or a walk through the product.

+ - **Duplicate:** of a named issue that stays open.

+ - **Slice of a cause:** group issues by the fix that would make them all

+ disappear, not by how each was reported. A slice is a checkbox in the

+ cause's `## Done when` (its details are copied into the cause and it

+ closes), or a sub-issue that stays open because it is a real separate

+ piece of work.

+ - **Cause:** its own issue, with the reason it is a different cause from

+ the ones it looks like.

+ - **Wrong premise:** ask of every issue whether the fix it asks for is a

+ workaround: raising a timeout, adding a retry, an exceptions list,

+ running things one at a time, one copy per language. If so, give it a

+ title and a `## Proper fix` for the real fix, and hang it under the

+ issue that owns that fix.

+ - **Out of date:** the code or release it describes has moved on ("Release

+ 0.1.166" after 0.1.170 shipped). Name the evidence; this is not a scope

+ decision and does not wait on the owner.

- **Still real:** you reproduced it or read the code that still has it.

- - **Unsure:** name the one exact check that would settle it.

- 3. **Never decide scope.** Dropping a feature, changing a priority or answering

+ - **Unsure** is not a parking spot. Run the check that settles it. Unsure

+ stands only when that check is truly impossible here, and the verdict

+ names the check and why it cannot run.

+ 4. **Keep each milestone to about 10 causes.** A milestone that ends with more

+ needs a reason in the plan; most often the excess are slices of a cause

+ already there.

+ 5. **Never decide scope.** Dropping a feature, changing a priority or answering

a decision goes to the owner as a question, using the client's question

tool where it has one, with the facts behind each choice.

- 4. **Report to the owner:** each issue closed, its reason and proof; each

- duplicate and the issue it went into; each issue left open, with its

- verdict; and the decisions waiting on them. Name every issue as a link with

- its title.

+ 6. **Show the plan before changing anything.** Run

+ `audit plan --repo R --plan PLAN.json [--verdicts BATCH.json ...] --page PAGE.md`

+ until it exits 0. It writes a short page: open and top-level counts before

+ and after per milestone, each cause with its slice count, what closes, and

+ every unsure issue with its check. Show the owner that page, as a page they

+ can open where the client can publish one, never the plan file itself.

+ 7. **Apply only what they approved.** Run

+ `audit apply --repo R --plan PLAN.json [--verdicts ...] --approved CODE`

+ with the code `plan` printed. It refuses a plan that changed since the page

+ was written, then creates new causes, moves slices under their causes,

+ copies folded details in, and closes through close-issues, deepest issues

+ first. A failed run is safe to rerun; it resumes.

+ 8. **Report to whoever asked**, in their channel: the owner's chat, or the

+ conductor's or peer session's pane when an agent asked, never only printed

+ where nobody is looking. Lead with outcomes as counts before and after

+ ("312 open issues are now 41 causes in 4 milestones; 120 closed with

+ proof"), then the decisions waiting on the owner. Name every issue as a

+ link with its title.

- Done when the script exits 0, every open issue in scope has a verdict, and the

- owner has the report.

+ Done when scan exits 0, every open issue in scope has a verdict, the owner

+ approved the page, apply finished, and the person who asked has the report.

</what-to-do>