1
---
2
name: stale-git-branch-cleanup-auditor
3
description: Audits a repository's remote branches and plans a safe cleanup. Sorts each branch into delete (merged, squash-merged or empty), archive then delete (idle unmerged work), ask the owner, open PR, active or protected, and groups the asks by author. Flags case-colliding names, stale PRs, branches far behind main, long-lived branches and bad names, and prints a reviewable tag-then-delete script. Includes a stdlib Python auditor with --self-test.
4
---
5
6
# Stale Git Branch Cleanup Auditor
7
8
You help teams clean up the dozens or hundreds of forgotten branches on a shared remote without losing anyone's work. You decide, branch by branch, what is safe to delete, what should be archived as a tag first, and who has to be asked, then produce a cleanup script that people review before anything is removed.
9
10
## Files in this skill
11
12
- `scripts/branch_audit.py` - classifies remote branches from a TSV or CSV export or straight from a local clone (`--repo`), prints findings, owner lists and a cleanup script (Python 3 standard library only; never deletes anything itself)
13
- `references/cleanup-rules.md` - the decision rules, squash-merge detection, archive tags, protected branches, naming conventions and how to restore a deleted branch
14
- `references/exporting-branch-data.md` - git and GitHub/GitLab commands to produce the input, including PR states
15
- `templates/cleanup-announcement.md` - a team message with the plan, the owner asks and the deadline
16
- `examples/webshop-branches.csv` - 16 branches of an online shop repository with merged, squash-merged, stale, colliding and protected branches
17
18
## Workflow
19
20
### 1. Get the branch data
21
Preferred: a fresh local clone (`git fetch --prune origin`) and run the script with `--repo`. Ask for the base branch (main, master or develop), the PR states from `gh pr list` or the GitLab API (squash merges cannot be seen in git history), the protected branch patterns and the team's naming convention. If they paste a list instead, convert it to the CSV columns in `references/exporting-branch-data.md`.
22
23
### 2. Run the auditor
24
```
25
python3 scripts/branch_audit.py examples/webshop-branches.csv --today 2026-10-24
26
python3 scripts/branch_audit.py --repo . --base main --prs prs.tsv --stale-days 90 --ask-days 30
27
python3 scripts/branch_audit.py --self-test
28
```
29
Exit code 1 means HIGH findings, 2 means bad input.
30
31
### 3. Review with the user
32
Walk through the actions in this order: DELETE_MERGED (safe, the work is in the base branch), ARCHIVE_AND_DELETE (recoverable from the archive tag), ASK_OWNER (needs an answer), then the findings. Fix CASE_COLLISION first because it breaks clones on macOS and Windows. Adjust thresholds to the team's pace (a research repo may want 180 stale days). Use `references/cleanup-rules.md` to explain each decision.
33
34
### 4. Deliver
35
Fill `templates/cleanup-announcement.md` with the counts, the per-owner list and a deadline (usually 7 days). Hand over the generated script with the advice to run the DELETE_MERGED lines first and the archive lines after the deadline.
36
37
## Example result
38
For `examples/webshop-branches.csv` (as of 2026-10-24, stale 90 days, ask 30 days): 16 branches -> 3 delete (merged, squash-merged PR, no commits ahead), 3 archive and delete (spike/graphql-gateway, feature/gift-cards, johns-test), 2 ask owner, 3 open PRs, 1 active, 4 protected. Findings: HIGH CASE_COLLISION (fix/search-timeout vs fix/Search-Timeout), MEDIUM PR_STALE (feature/checkout-redesign, idle 205 days), 3 MEDIUM FAR_BEHIND, 2 LOW BAD_NAME, 2 LOW LONG_LIVED, LOW OLD_PROTECTED (release/2.3).
39
40
## Rules
41
42
- Never delete branches yourself and never run the script for the user; print it for review.
43
- Unmerged work is archived as a tag (`archive/<branch>`) before the branch is deleted, so it can be restored.
44
- Squash and rebase merges leave the branch "unmerged" in git; trust the PR state, not only `--merged`.
45
- Protected, release and base branches are never in the delete list, even if they look idle.
46
- Ask owners before touching unmerged work and give a clear deadline.
47