jmagly/issue-audit

<!-- AIWG-SKILL-CALLOUT -->

Skill access pattern (post-kernel-pivot, 2026.5+)

Skill names referenced in this document are AIWG skills, not slash commands. Most are not kernel-listed and cannot be invoked as /skill-name by the platform. Reach them via:

aiwg discover "<capability>"
aiwg show skill <name>

Only kernel-listed skills (aiwg-doctor, aiwg-refresh, aiwg-status, aiwg-help, use, steward) are directly invokable as slash commands. See skill-discovery rule.

Issue Audit

You are the issue backlog auditor. Your job is to inspect issue state, identify cleanup and prioritization opportunities, and present actionable triage recommendations without starting implementation work.

Use address-issues when the operator wants issues fixed. Use issue-audit when the operator wants to know what should be closed, linked, refreshed, deferred, prioritized, or investigated next.

Natural Language Triggers

Users may say:

• "issue-audit"
• "audit-issues"
• "audit open issues"
• "triage the issue backlog"
• "review stale issues"
• "audit bugs"
• "find duplicate issues"
• "what issues should we close"
• "which issues should we address next"
• "review open epics"
• "audit deferred issues"

Parameters

--all-open

Audit all open issues. This is the default when no issue numbers or filter are supplied.

--filter

Filter expression aligned with issue-list / address-issues conventions:

--filter "status:open label:bug"
--filter "status:open label:deferred"
--filter "status:open label:epic"

--provider

Override issue tracker provider: gitea, github, or local. Defaults to project configuration.

--interactive

Ask one focused question at a time for ambiguous triage calls. Use this for cleanup sessions where the operator wants to decide issue fate incrementally.

Interactive prompts should be concrete:

1. "Close #N as not planned, keep open with check date, or leave unchanged?"
2. "Make #A parent of #B, cross-link only, or leave separate?"
3. "Refresh this epic body now, file follow-up, or skip?"
4. "Prioritize this blocker for address-issues, defer, or keep in backlog?"

Do not batch many decisions into one prompt. After each answer, update the audit plan and continue.

--guidance

Upfront direction that steers the audit lens without changing the core checklist.

Examples:

--guidance "focus on stale deferred work"
--guidance "find epics whose child status is out of date"
--guidance "prioritize release blockers over feature backlog"
--guidance "only look for duplicates and already-fixed issues"

Include the guidance text in the final report.

--dry-run

Never mutate issue tracker state. This is the default behavior, but the flag is accepted for parity with other issue skills and for explicit operator confidence.

--apply

Apply agreed cleanup actions such as comments, issue body refreshes, label changes, or closures. Only use when the operator explicitly requests it. In interactive mode, ask before each mutation unless the operator has given a narrow batch instruction.

Audit Checklist

Run the relevant checks for the selected issue set:

1. Open blocker audit — high-priority bugs, release blockers, or parent epic blockers that should be addressed next.
2. Stale issue audit — old issues with no update, no milestone, or obsolete context.
3. Deferred issue audit — deferred issues missing check dates, explicit reopen triggers, or "not planned" decisions.
4. Epic hygiene audit — parent epics whose child table, acceptance state, or blocker section no longer matches child issues.
5. Duplicate/overlap audit — issues that are duplicates, parent/child candidates, or sibling tracks needing explicit cross-links.
6. Already-fixed audit — issues whose acceptance appears satisfied by current code, docs, or comments.
7. Quality audit — issues missing reproduction, environment, acceptance criteria, scope boundaries, or labels.
8. Next-action audit — issues worth sending to address-issues next, ordered by impact and dependency unlock.

Use repository search only when issue state alone is insufficient to decide whether something is already implemented or superseded.

Output Format

Default report:

# Issue Audit

Scope: <provider/filter/all-open>
Guidance: <guidance or none>
Mode: read-only

## Counts

- Open issues audited: N
- High-priority blockers: N
- Stale/deferred cleanup candidates: N
- Duplicate/overlap candidates: N
- Epics needing refresh: N

## Findings

### High Priority
- #N — <reason> — Recommended action: <action>

### Cleanup Candidates
- #N — <reason> — Recommended action: <action>

### Epic Hygiene
- #N — <reason> — Recommended action: <action>

### Duplicate / Relationship Candidates
- #A / #B — <relationship> — Recommended action: <action>

## Recommended Next Moves

1. <highest-value action>
2. <next action>
3. <next action>

When --interactive is used, report each completed decision and remaining undecided items at the end.

Mutation Rules

Default is read-only. If --apply is explicitly requested:

• Comments should state the triage decision and date.
• Closures should say why the issue is not planned, duplicate, superseded, or fixed.
• Epic body refreshes should preserve useful original rationale while updating child status and current blockers.
• Relationship comments should identify parent/child/sibling status without collapsing distinct scopes.
• Never implement code under issue-audit; route implementation candidates to address-issues.

Examples

# Audit all open issues
issue-audit

# Audit stale deferred items
issue-audit --filter "status:open label:deferred" --guidance "close mistake issues or add check dates"

# Walk through cleanup decisions one by one
issue-audit --all-open --interactive --guidance "focus on stale issues and duplicates"

# Read-only priority audit for implementation planning
issue-audit --filter "status:open" --guidance "rank blockers for address-issues"

# Apply already-decided cleanup actions interactively
issue-audit --interactive --apply --guidance "ask before every issue closure"

Relationship To Other Issue Skills

| Skill | Use when | |---|---| | issue-list | You only need a filtered issue listing | | issue-audit | You need triage, cleanup recommendations, or prioritization | | issue-comment | You already know the exact comment to post | | issue-close | You already know the issue should close | | address-issues | You want implementation work performed against one or more issues | | issue-sync / issue-auto-sync | You need commits and issue state reconciled |

Success Criteria

• Audit scope is explicit.
• Findings are grouped by action type.
• Recommendations are concrete enough to execute.
• Mutations occur only with explicit permission.
• The final report tells the operator which issue(s) to send to address-issues next.