| name | github-health-branches |
| description | Audit GitHub branch hygiene: merged branches, stale branches, orphan branches, branches behind main, branch naming risks, and branch cleanup candidates. Triggers on `/github-health branches <repo>` and requests like "review branches", "which branches can I delete", "branch cleanup", or "are there stale branches". Use this for branch-only cleanup; for cross-cutting cleanup (branches + PRs + issues + docs + security + Linear) use github-health-cleanup-plan instead. Read-only; never deletes branches without explicit approval. |
github-health-branches
When to trigger
/github-health branches <repo>- Requests about branch cleanup, stale branches, orphan branches, or naming risks.
Required inputs
- GitHub repository URL.
- Optional: a "stale" threshold in days (default: 60).
Reference files
github-health/references/github-health-checklist.md — Section 4.github-health/references/scoring-model.mdgithub-health/references/severity-model.mdgithub-health/references/output-contract.mdgithub-health/references/safety-rules.mdgithub-health/references/collection-guide.md
Procedure
- Fetch all remote refs (
git fetch --all --prune).
- List branches with last-commit date and author.
- Determine which branches are merged into the default branch and which are not.
- Classify each branch:
- Active — recent commits and an open PR or recent activity.
- Merged-undeleted — merged into default, no longer needed.
- Stale — no activity past the threshold and no open PR.
- Orphan — no associated PR, ahead of default, no recent activity.
- Long-lived feature — open PR but diverging significantly from default.
- Inspect branch names for risk patterns:
- Names that include
Closes #N, Fixes #N, or Linear-style IDs that could trigger auto-close on push or merge.
- Names that imply security context but are not in a private workflow.
- Score the Branch hygiene area (weight 10) per
scoring-model.md.
- Produce a cleanup candidates list with severity and rationale.
- Surface deletions only under Approval Required Before Destructive Actions.
Evidence to collect
git fetch --all --prune
git for-each-ref --sort=-committerdate refs/remotes/origin \
--format="%(committerdate:iso8601) %(refname:short) %(authorname)"
git branch -r --merged origin/<default>
git branch -r --no-merged origin/<default>
gh pr list --state open --json number,headRefName,baseRefName,updatedAt
Red flags
- [HIGH] Long-lived branch (>60 days) with significant divergence and no open PR.
- [MEDIUM] Branch merged into default but not deleted, > 30 days.
- [MEDIUM] Many orphan branches relative to active development.
- [MEDIUM] Inconsistent naming (mix of
feat/, feature/, f-, none).
- [LOW] Personal/scratch branches (
tmp/foo, wip/x) older than 30 days.
- [HIGH] Branch name contains
Closes <linear-id> or Fixes #N and is open against default — risk of accidental auto-close on merge.
Output format
Use the standard contract. Populate Detailed Findings → Branches in depth, plus a clearly labeled Cleanup Candidates subsection inside it. Each candidate row should include:
- Branch name.
- Last commit date and author.
- Status (merged / stale / orphan / long-lived).
- Recommendation (delete after final confirmation, leave, or escalate).
- A one-line rollback note if deletion is recommended.
Safety rules
- Never delete a branch in this skill, ever.
- All deletions are listed under Approval Required Before Destructive Actions.
- Recommend
git push origin --delete <branch> only as a manual command for the user to run after their explicit confirmation.
- Always note recovery options (e.g., "branch ref can be restored from
git reflog or from the merge commit's parent").
When to escalate
If branch protection is absent or the default branch contains direct pushes from many contributors, recommend /github-health full <repo> to inspect protection and CI as well.
What not to do
- Do not bulk-recommend deletion of every branch matching a pattern. Each recommendation must be evaluated individually with evidence.
- Do not assume "merged" implies "safe to delete" — if the branch is referenced by a release tag, deployment, or downstream fork, deletion may break links.
