---
name: stale
description: Housekeeping report — find stale PRs, orphan branches, stale issues, and stale plans
argument-hint: [days]
---

# Stale: Housekeeping Report

Arguments: `$ARGUMENTS`

Parameters (all optional):
- **days** — staleness threshold in days, defaults to 14

## Repository Data

Open PRs with metadata:

!`gh pr list --state=open --json number,title,author,createdAt,updatedAt,isDraft,reviewDecision,headRefName,additions,deletions --limit 100 2>/dev/null || echo "GH_ERROR"`

Open issues:

!`gh issue list --state=open --json number,title,assignees,createdAt,updatedAt,labels --limit 100 2>/dev/null || echo "GH_ERROR"`

Local branches with last commit date:

!`git branch --format='%(refname:short) %(committerdate:iso8601)' 2>/dev/null | grep -v '^main$' | grep -v '^master$'`

Branch-to-PR mapping:

!`git branch --format='%(refname:short)' | grep -v '^main$' | grep -v '^master$' | while IFS= read -r b; do PR=$(gh pr list --head "$b" --state=open --json number --jq '.[0].number' 2>/dev/null); echo "$b -> ${PR:-none}"; done`

Plan files (if docs/plans/ exists):

!`if [ -d docs/plans ]; then find docs/plans -name '*.md' -not -path '*/archive/*' 2>/dev/null; else echo "NO_PLANS_DIR"; fi`

Plan file contents (frontmatter only, for status/date checking):

!`if [ -d docs/plans ]; then find docs/plans -name '*.md' -not -path '*/archive/*' 2>/dev/null | while IFS= read -r f; do echo "=== $f ==="; head -20 "$f" 2>/dev/null; echo; done; else echo "NO_PLANS_DIR"; fi`

## Instructions

You are producing a **housekeeping report** — identifying stale items that need cleanup, closure, or attention.

### Step 1: Triage

If any data block shows `GH_ERROR`, report that `gh` failed (likely auth or network) and stop.

Parse the days threshold from arguments (default 14). An item is "stale" if it hasn't been updated in more than this many days.

### Step 2: Analyze

For each category, identify stale or orphaned items:

**Stale PRs** — Open PRs where `updatedAt` is older than the threshold.

**Orphan branches** — Local branches that have no open PR (mapped to `none` in the branch-to-PR data). For each orphan, check if it's been merged into main:
```
git branch --merged main
```
An orphan that's already merged into main is a safe delete candidate. An unmerged orphan needs investigation.

**Stale issues** — Open issues where `updatedAt` is older than the threshold.

**Stale plans** — Plan files in `docs/plans/` (not in `archive/`) that appear completed, have a past target date, or haven't been updated recently. Check frontmatter for `Status` and date fields.

### Step 3: Write the report

Produce the following sections:

---

#### Summary

A single compact line:

> **2 stale PRs, 3 orphan branches, 1 stale issue, 0 stale plans**

#### Stale PRs

A table for each stale PR:

| PR | Title | Author | Age | Status | Suggested Action |
|----|-------|--------|-----|--------|-----------------|

Status should reflect: `DRAFT`, `AWAITING REVIEW`, `CHANGES REQUESTED`, `APPROVED`.
Suggested actions: "Close — appears abandoned", "Ping author for update", "Needs rebase", "Review and merge — approved but stale", etc.

If no stale PRs, say "None — all PRs are active."

#### Orphan Branches

List each orphan branch with:
- Branch name
- Last commit date
- Whether it's merged into main
- Suggested action: "Safe to delete (merged)" or "Investigate — unmerged and has no PR"

If no orphan branches, say "None — all branches have open PRs."

#### Stale Issues

A table for each stale issue:

| Issue | Title | Assignee | Age | Labels | Suggested Action |
|-------|-------|----------|-----|--------|-----------------|

Suggested actions: "Close — likely resolved", "Needs triage", "Reassign — assignee may be unavailable", etc.

If no stale issues, say "None — all issues are active."

#### Stale Plans

List plan files that appear stale:
- File path
- Status from frontmatter (if present)
- Why it's flagged (completed, past target date, no recent updates)
- Suggested action: "Archive to docs/plans/archive/", "Update status", "Delete if superseded"

If `docs/plans/` doesn't exist or has no stale plans, say "None."

#### Quick Wins

List exact commands the user can copy-paste to clean up safe-to-delete items. **Do not execute these — list them only.**

Examples:
```
git branch -d feature/old-branch    # merged, safe to delete
git push origin --delete feature/old-branch  # clean up remote
gh pr close 42 --comment "Closing stale PR — superseded by #57"
```

If there are no quick wins, omit this section.

---

### Formatting rules

- Use markdown tables for PRs and issues
- Reference PR/issue numbers as `#N`
- Show ages as "X days" (compute from current date vs `updatedAt` or commit date)
- Keep it scannable — this is a cleanup checklist, not a deep analysis
- Be specific in suggested actions — generic "review this" isn't helpful

## Escalation

Stop and tell the user when:
- `gh` commands fail (auth, network, or unexpected errors)
- Any list returns at its limit cap (100 results) — the repo may have more items than shown