Update: Issue Audit & Cleanup

Audit open GitHub issues for staleness, drift, and hygiene problems. Categorize findings and execute approved remediations.

Workflow

1. Auth Check → 2. Detect Repo → 3. Fetch Issues → 4. Pass 1: Metadata Audit
→ 5. Pass 2: Codebase-Aware Audit → 6. Categorize → 7. Present Report
→ 8. Interactive Remediation → 9. Execute Actions → 10. Summary

Step 1: Verify GitHub Auth

gh auth status

On failure: Stop and tell the user to run gh auth login.

Step 2: Detect Repository

gh repo view --json nameWithOwner -q .nameWithOwner

On failure: Ask the user for the target repository (owner/repo).

Step 3: Fetch Open Issues

gh issue list --state open --limit 100 --json number,title,body,labels,assignees,milestone,createdAt,updatedAt,author

Edge case — no open issues: Report "No open issues to audit" and stop.

Edge case — 100+ issues: Warn the user that results are capped at 100. Suggest filtering by label or milestone for larger backlogs.

Step 4: Pass 1 — Metadata Audit

Check each issue for these problems:

Check	Condition	Severity
Stale	No updates in 30+ days	Medium
Ancient	No updates in 90+ days	High
Orphaned blocker	References Blocked by: #<number> where the referenced issue is closed (see batch verification note below)	Medium
Completed sub-tasks	All - [x] checkboxes checked but issue still open	High
Missing labels	No type label (bug, enhancement, etc.)	Low
Missing priority	No priority label (P0-P3)	Low
Abandoned assignment	Assigned but no updates in 14+ days	Medium

For each issue, collect all matching problems into a findings list.

Batch verification for orphaned blockers: Step 3 already fetches all open issues. Any blocker reference (Blocked by: #<number>) where the number is absent from the open set is treated as resolved — no extra API call needed. Only use gh issue view for edge cases where you need to distinguish "closed" from "never existed".

Step 5: Pass 2 — Codebase-Aware Audit

For issues that reference specific files or features, cross-check against the codebase:

File Drift

For issues whose body contains file paths (e.g., src/auth/login.ts):

1. Extract file paths from issue body
2. Determine intent from surrounding context — paths under headings like "Files to Create" or prefixed with "create", "add", "new" are expected to not yet exist; skip these
3. Use Glob to check if remaining paths still exist
4. If files are missing/moved, flag as file-drift

Already Implemented

For feature requests and bug fixes:

1. Extract key implementation details from the issue body (function names, component names, patterns)
2. Use Grep to search for those patterns in the codebase
3. If the feature appears to already exist, flag as possibly-implemented

Related Branches and PRs

gh pr list --state all --search "ISSUE_NUMBER" --limit 5 --json number,title,state,mergedAt

Check if:

• A merged PR references this issue → flag as has-merged-pr (strong close candidate)
• An open PR references this issue → flag as has-open-pr (in progress, not stale)

Step 6: Categorize Issues

Sort issues into five categories based on findings:

Category	Criteria	Suggested Action
Close Candidates	Has merged PR, all checkboxes done, or flagged as possibly-implemented	Close with comment
Update Needed	Orphaned blockers, file drift, stale assignment	Edit issue metadata
Needs Triage	Missing labels, missing priority, no clear scope	Add labels, clarify scope
Stale	30-90 days inactive, no PR activity	Ping assignee or add stale label
Healthy	Recently active, properly labeled, has assignee or clear owner	No action needed

Step 7: Present Report

Show a structured report by category:

## Issue Audit Report

### Close Candidates (3 issues)
| Issue | Title | Reason |
|-------|-------|--------|
| #12 | Add user avatars | Merged PR #45, all acceptance criteria met |
| #18 | Fix login redirect | Feature already implemented (found in src/auth/redirect.ts) |
| #23 | Update deps | Ancient (142 days), no activity |

### Update Needed (2 issues)
| Issue | Title | Problem | Fix |
|-------|-------|---------|-----|
| #31 | Refactor API layer | Blocked by #12 (closed) | Remove stale blocker reference |
| #35 | Add caching | References src/old/cache.ts (deleted) | Update file paths |

### Needs Triage (4 issues)
| Issue | Title | Missing |
|-------|-------|---------|
| #40 | Something about auth | No type label, no priority |
| #41 | Performance issue | No priority label |
| ... | ... | ... |

### Stale (2 issues)
| Issue | Title | Last Activity | Assignee |
|-------|-------|---------------|----------|
| #28 | Add dark mode | 45 days ago | @alice |
| #33 | Improve tests | 38 days ago | unassigned |

### Healthy (8 issues)
✓ 8 issues are properly maintained — no action needed.

### Summary
- 3 close candidates
- 2 issues need metadata updates
- 4 issues need triage
- 2 stale issues
- 8 healthy issues

Step 8: Interactive Remediation

For each non-healthy category, use AskUserQuestion to get approval:

Close Candidates:

Question: "How should I handle close candidates?"
Options:
  - Close all 3 with a comment
  - Let me review each one individually
  - Skip — don't close any

Update Needed:

Question: "Should I fix the metadata issues?"
Options:
  - Fix all automatically
  - Let me review each fix
  - Skip — I'll handle these manually

Needs Triage:

Question: "Should I add missing labels?"
Options:
  - Add suggested labels to all
  - Let me review each suggestion
  - Skip

Stale Issues:

Question: "How should I handle stale issues?"
Options:
  - Add 'stale' label to all
  - Comment pinging assignees
  - Skip

For "review each" options, iterate through issues one at a time with per-issue AskUserQuestion.

Step 9: Execute Approved Actions

Run approved actions using gh CLI:

Closing issues:

gh issue close ISSUE_NUMBER --comment "Closing: [reason]. Identified by /pm:update audit."

Editing issue metadata:

gh issue edit ISSUE_NUMBER --add-label "label-name"
gh issue edit ISSUE_NUMBER --remove-assignee "username"

Removing stale blocker references:

gh issue comment ISSUE_NUMBER --body "Removed stale blocker reference to CLOSED_ISSUE_NUMBER (now closed). Issue is unblocked."

Pinging stale assignees:

gh issue comment ISSUE_NUMBER --body "@username — This issue hasn't been updated in [X] days. Are you still working on it? If not, I can unassign so someone else can pick it up."

Step 10: Print Summary

After all actions complete, print a final summary:

## Audit Complete

| Action | Count | Issues |
|--------|-------|--------|
| Closed | 3 | #12, #18, #23 |
| Labels added | 4 | #40, #41, #42, #43 |
| Blockers cleaned | 1 | #31 |
| Stale pings sent | 2 | #28, #33 |
| Skipped | 0 | — |

Total: 10 actions taken across 10 issues.

Suggest: "Run /pm:next to see what to work on now that the backlog is cleaned up."