Stack-Audit

Detects gaps in the issue↔PR pipeline so nothing escapes the current stack.

Checks

1. Orphan PRs (PR with no issue reference)

gh pr list --state open --json number,title,body,headRefName

For each PR, check if the body contains Closes #N, Fixes #N, Refs #N, or Resolves #N. If none found → orphan PR.

Flag: orphan-pr label suggestion + comment recommending issue creation.

2. Stale Issues (issue ready/in-progress with no PR)

gh issue list --state open --json number,title,labels

For each issue with label ready-to-implement (or equivalent), check if there's an open PR referencing it. If not → stale issue.

Flag: comment with "No PR open for this issue — consider creating one or closing if obsolete."

3. Merged PR, Issue Still Open

gh pr list --state merged --json number,title,body --limit 100

For each merged PR with Closes #N, verify issue #N is closed. If open → close gap.

Action: do not close automatically. Surface the gap in the findings list and let the user confirm. Only after explicit user approval run:

gh issue close #N --reason completed

Closing an issue is a state change on the tracker; never perform it without user confirmation, and never batch-close multiple issues in one pass.

4. Closed Issue, No Merged PR

gh issue list --state closed --json number,title,body --limit 100

For each closed issue, check if there's a merged PR referencing it. If not → escaped issue (closed without implementation evidence).

Flag: escaped-issue label suggestion. May need reopening or a follow-up issue.

5. Library Opportunities

During context-load and stack-audit, if a dependency or library could simplify the solution to an open issue:

• Do NOT bundle it into the current issue
• Create a separate enhancement issue with labels enhancement + library-review
• Reference it from the main issue: Related: #NN (library review)

The library-review issue should contain:

• Library name and link
• What problem it solves
• Which open issues it could improve
• Trade-offs (license, bundle size, maintenance status)

Output

Write findings to the progress file:

## Stack-Audit Findings

### Orphan PRs
- PR #NN "title" — no issue reference

### Stale Issues
- Issue #NN "title" — no open PR

### Close Gaps
- PR #NN merged but issue #MM still open

### Escaped Issues
- Issue #NN closed but no merged PR

### Library Opportunities
- [library name] could simplify issue #NN — create enhancement issue

Parallel Execution

Stack-audit can run in parallel with context-load. Both feed into issue-craft.

Pagination

The default --limit is set to 100 (not 20) to cover most repos in a single call. For very large repos with more than 100 open/merged items:

• Use --limit 200 or higher if the API allows it
• Make multiple paginated calls with --limit 100 and track the last seen number to avoid duplicates
• For targeted queries, use gh search prs / gh search issues with search terms instead of listing everything:

  gh search prs --state open --review-requested @me
  gh search issues --state open --label "ready-to-implement"

• Document in the findings if pagination was used and whether all pages were consumed

Empty State Handling

• No open issues: report Open issues: 0 and note "No open issues — stack is clean or tracker is unused." Proceed to PR checks.
• No open PRs: report Open PRs: 0 and note "No open PRs." Proceed to issue checks.
• No issues AND no PRs: report "Empty stack — no issues or PRs found. Repo may be new or gh may lack access." Suggest verifying gh auth status.
• No merged PRs: skip check 3 (close gaps). Note "No merged PRs — close gap check skipped."
• No closed issues: skip check 4 (escaped issues). Note "No closed issues — escaped issue check skipped."

Error Handling

• gh CLI not installed: stack-audit cannot run without gh. Report "gh CLI not found — stack-audit skipped. Install: https://cli.github.com/" and continue with context-load only.
• gh not authenticated: run gh auth status to confirm. If not authed, report "gh not authenticated — run gh auth login and retry." Do not attempt to authenticate automatically.
• GitHub API rate limits: if a gh command returns a rate limit error, stop and report "GitHub API rate limited — retry after [reset time]. Partial findings may be incomplete." Note which checks completed and which were skipped.
• Required files/directories don't exist: stack-audit operates on GitHub data, not local files. If the repo has no .github/ directory, that's expected — templates are checked by context-load, not stack-audit.
• Commands fail: if a gh command fails (network error, permission denied), record the error in findings as [check name]: failed — [error message] and continue with the next check. Do not abort the entire audit.

Example

Filled-in findings for a sample project:

## Stack-Audit Findings

### Orphan PRs
- PR #42 "feat: add leaderboard UI" — no issue reference

### Stale Issues
- Issue #17 "fix: flashlight uses :Fire() instead of :FireServer()" — no open PR

### Close Gaps
- PR #38 merged but issue #29 still open — awaiting user confirmation

### Escaped Issues
- Issue #51 closed but no merged PR — may need follow-up

### Library Opportunities
- Roact could simplify issue #17 (UI state management) — create enhancement issue