agentleFS
wardawgmalviciouswardawgmalvicious/agent-config/skills/workflow/prune-branches/SKILL.md

prune-branches

Skill1 starsChanged 34 days agoMITView on GitHub

Audits every branch a repo carries — local, remote, and worktree-pinned — and sorts them into safe to delete, stale, and carrying unmerged work, rescuing the last group onto a fresh verified branch before recommending anything. Built for repos that squash-merge, where `git branch --merged` and `git cherry` both report merged branches as unmerged because patch-ids never match, so merge evidence has to come from the PR list instead. Separates a stale remote-tracking ref from a branch that really is still on the remote. Reports and recommends; never deletes a branch and never pushes a deletion. Complements land, which prevents this debris on the happy path — this cleans up what never took it.

  • Commits and pushes

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read this before deciding the ladder below is over-careful and the obvious finish is to delete the safe branches yourself.

    line 19
  2. Distinctive:

    Commits that cancel exactly: Verify with a diff across the span, not by reading the messages — a revert pair is obvious in the log and a …

    line 208
  3. Distinctive:

    When nothing cleared, say so in as many words.

    line 290
  4. Distinctive:

    Never delete a branch and never push a deletion: Not local, not remote, not "the obviously safe ones", not when told to.

    line 319
  5. Very specific:

    Zero commits ahead is a complete answer: Do not read content to confirm what rev-list already settled.

    line 327
  6. Very specific:

    State the limits in the report: only squash-merge GitHub was validated, and rung 2 depends on gh.

    line 329

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Pruning branches

Enumerate every branch a repo carries, establish for each whether its work is already in main, and end at a verdict table plus the exact deletion command for the user to run.

Audit and report is the design, not caution

Read this before deciding the ladder below is over-careful and the obvious finish is to delete the safe branches yourself.

The deletion is not yours to run, and attempting it burns the turn. Claude Code's auto-mode classifier denies git push origin --delete as [Git Destructive]. That denial is correct and it is not going away, so a skill whose payoff step is the deletion fails its last step every time — observed on four branches that had already been verified safe. A verified recommendation is where the value actually is and where the permission model already allows it to land.

The local half is not the soft half. In a squash repo git branch -d refuses the very branches the audit clears — its merged check is the one rung 2 says is wrong — so the only local deletion that works is -D, the forced form, on a verdict git itself disputes. Measured 2026-09-14: after git merge --squash, git branch --merged main omitted the branch and -d answered not fully merged. Not local, not remote: both go in the command string.

So the output is a table and a command string. The user runs it.

An instruction to delete does not lift this. "Just delete them", "don't make me run anything", "I trust your call on which are dead" — each is the case this section exists for, not a waiver of it. The two reasons above are reasons, not conditions: a permission mode the user could loosen and a -d the user could force do not make the deletion yours once they are gone. Reasoning from the mechanism is exactly how the refusal was lost — measured 2026-09-14 on both invocation paths, under a query that delegated the classification: the skill read its own no-delete rule as the user's to waive, and used the -D fact as guidance for deleting rather than grounds for not. The shape to hold is land's Absolute constraints — an instruction to do these is a stop, not an override. Say so once, give the table and the command, and stop.

The allowed-tools line encodes that split, and it pre-approves rather than restricts. Every probe the audit needs is listed, so the read-only half runs without a prompt per branch; no mutating command is listed, so the cherry-pick, the worktree removal and the deletion stay prompted. Listing a write would not enable anything currently blocked — it would remove the prompt that keeps this skill honest. The guard is this rule, not the field.

1. Detect the merge style first

The whole ladder below exists to work around squash-merge. Check before performing it, or you will do four rungs of unnecessary work and present it as rigor.

git log --merges --oneline | wc -l
gh pr list --state merged --limit 100 | wc -l

Near-zero merge commits against many merged PRs means squash or rebase — continue to step 2.

Many merge commits means merge-commit style, where git branch --merged main is accurate and sufficient. Say so, run it, report, and stop. Do not perform the rungs.

Only the squash path is evidence-backed. This procedure was validated end to end on one squash-merge GitHub repo. Under rebase-merge the failure mode is the same as squash — patch-ids do not survive the rewrite — but the remedy may differ, and that was not tested. Under merge-commit style the early exit above is the whole skill. State whichever limit applies in the report rather than implying all three were covered.

2. Rung 0 — establish what actually exists

git fetch origin --prune
git worktree list
git ls-remote --heads origin

git branch -a shows neither of the two findings that live here.

A branch pinned by a worktree cannot be deleted at all. The error names the worktree path, and removing the worktree is the fix: git worktree remove <path> while the directory exists, git worktree prune when it was deleted by hand and only its entry under .git/worktrees survives — git worktree list shows which. Both are writes, so propose them, do not run them.

A worktree marked locked refuses both, one --force included: fatal: cannot remove a locked working tree, lock reason: <reason>, while prune skips it and says nothing (git 2.55, 2026-09-25). The refusal's second line suggests remove -f -f: never propose it. It removed a locked, dirty worktree in one step, uncommitted changes and all, past both checks below (2026-09-29, and git-worktree's docs). git worktree list -v prints the reason. A claude --worktree session locks its own as claude session <name> (pid <n>), and one killed with its terminal, never /exited, left the lock behind, its pid dead (2026-09-24). A live pid is a session still working there: leave it. A pid held by anything but claude was reused, so that session is dead: Get-Process -Id <n> names the holder, and Windows recycles pids. Otherwise git worktree unlock <path> goes ahead of the removal, a deleted directory's included. Read git -C <path> status --short first: a worktree's uncommitted changes are on no branch, so no rung below sees them, and the --force a dirty tree needs discards them.

A remote-tracking ref is not evidence the branch is still on the remote. origin/<name> can survive locally long after the branch is gone. ls-remote asks the remote itself and is the only thing that settles it.

3. Rung 1 — ahead/behind

Per branch:

git rev-list --count main..origin/<branch>   # commits the branch has
git rev-list --count origin/<branch>..main   # commits it is behind by

Zero ahead ends the analysis. The branch is fully contained in main and is safe to delete regardless of how it got that way — no PR lookup, no content reading.

Anything with commits ahead goes to rung 2.

4. Rung 2 — merge evidence

gh pr list --state all --limit 100 --json number,headRefName,state,title

Key on headRefName. A PR whose head was this branch and whose state is MERGED is the merge evidence, and the branch is safe. The other two states both mean keep, for different reasons: CLOSED is work someone declined, still only on the branch, and goes on to rung 3; OPEN is work in flight — keep it, say so, and stop there, since a branch someone is actively landing needs no content archaeology. --limit 100 returns the hundred most recent, so an old branch's PR can fall outside it and read as no PR. That sends it to rung 3, the safe direction but not a free one; raise the limit, or confirm a missing one with gh pr list --state all --head <branch>.

git branch --merged and git cherry are both wrong here, and wrong in the dangerous direction. Squashing rewrites the commits, so patch-ids never match and both commands report squash-merged branches as unmerged. In the observed run git cherry flagged every commit on every remaining branch as unique — including on two branches that held nothing worth keeping. An agent that trusts it keeps everything forever; an agent that learns to override it deletes real work. Neither is a usable default, which is why merge evidence comes from the PR list.

This rung is GitHub-specific. It depends on gh. GitLab and Azure DevOps equivalents were not investigated — say so rather than presenting the skill as forge-agnostic.

gh may not be acting as the account you expect. The GitHub API actor is a third identity, bound separately from the commit author, and gh auth status reports the keyring's active account rather than the one gh will act as in this repo. Nothing here writes, so the full identity procedure in land is not needed — just do not tell the user that gh auth status says who they are.

Commits ahead and no merge evidence — no PR, or a CLOSED one — goes to rung 3.

5. Rung 3 — content recency

This is the rung that prevents the expensive mistake, and the one most likely to be skipped as redundant. Do not skip it.

"Has commits main does not" and "has work worth keeping" read as the same statement and are not. A branch that diverged from an old main looks identical, at commit level, to a branch carrying real work. The difference is only visible in the content.

Resolve it per contested file, comparing both sides:

git log -1 --format="%h %ad %s" --date=short origin/<branch> -- <path>
git log -1 --format="%h %ad %s" --date=short main -- <path>

In the observed run a branch whose seven unique commits looked substantial turned out to hold the older copy of its contested file — superseded on main by a later PR. Every commit-level signal rated it identical to the branches that carried real work.

6. Rung 4 — read what survives, and put judgment back to the user

Three patterns, all observed:

  • Commits that cancel exactly. Verify with a diff across the span, not by reading the messages — a revert pair is obvious in the log and a refactor-then-unrefactor pair is not:

    git diff --stat <first>^ <last> -- <paths>

    Empty output means the span is a no-op and the branch is safe.

  • Commits that contradict something the repo says about itself. This is where the skill sends you to the repo's own instructions before recommending a rescue. In the observed run a commit hand-applied a vendor format upgrade that the repo documented as a portal-only action — nothing in git would ever have flagged it, and rescuing it would have re-landed a change the repo forbids.
  • Genuinely unmerged work, which goes to step 7.

Teach the habit of asking, and stop there. This rung can name the question to ask; it cannot enumerate the answers, because they are properties of the repo rather than of git. Put the call back to the user with the evidence, and say plainly that it is a judgment call.

This is also where the logical commit split commit writes pays off: the survivors are readable as units because they were committed as units.

7. Rescue before recommending deletion

Any branch still holding real work after rung 4 is rescued, not deleted — but the rescue is an extraction, not a relocation. It exists to lift the survivors out of a branch that also holds junk, so the junk branch can go. A branch whose every commit survived, already named to convention, has nothing to extract: leave it where it is and say so. Cherry-picking it onto a fresh branch manufactures the very debris this audit is for. Observed 2026-09-14 on a one-commit branch with no PR: the whole branch was the survivor, and the right output was "keep".

In a tree another session shares, a switch moves its HEAD too: run ListAgents and read every row before the first command, as land step 1 does.

git switch main && git pull --ff-only
git switch -c <type>/<kebab-slug>
git cherry-pick <only the commits that survived rung 4>

Then verify with the repo's own validator and guard commands — read them out of the project instructions rather than assuming a test runner exists. A rescue that has not been run against the repo's own checks is a claim, not a result.

Report the new branch and hand the landing to land. Do not push it.

A kept branch is handed over the same way, and it is usually behind main — the rescue above is cut from fresh main and cannot be, but a branch left in place predates every merge since its fork point, and land's --ff-only refuses that rather than fixing it: it stops and says main has moved. git merge-base --is-ancestor main <branch> answers it (exit 0 means fine). If not, say so and ask the user whether to rebase it onto main before the handoff: a rebase rewrites its SHAs, and a branch already pushed would then need the force push land never makes.

8. Report, and stop

Emit three things:

  1. A verdict table — one row per branch: the branch, the rung that settled it, and the evidence that settled it. The rung number is the useful column; it tells the user how much to trust the row.
  2. The rescue branch, if any, with what was cherry-picked onto it and which checks it passed.
  3. The exact deletion command, for the user to run:

    git branch -D <branch> <branch> ...            # -d refuses squash-merged branches
    git push origin --delete <branch> <branch> ...

    When nothing cleared, say so in as many words. An empty set is a verdict, not a missing step — observed 2026-09-14 on a two-branch repo where both carried work.

Then stop. Do not run it, and do not offer to.

A cheap upstream fix exists. Enabling auto-delete-on-merge and branch protection stops most of this debris accumulating in the first place; worth one closing sentence to the user when the audit found a large set — and worth checking even when it found none, since a clean list can be land deleting what it merged rather than the setting: gh api repos/:owner/:repo --jq .delete_branch_on_merge read false on a repo with no debris at all, 2026-09-14.

Boundary with land

Both skills delete branches, and the split is clean in both directions.

land deletes a branch it has just merged, from a state it watched happen — its step 9 is deliberately ungated for exactly that reason, and that reasoning does not generalise. This skill handles branches whose provenance is unknown and which never went through land at all, which is why it gates by not deleting.

land prevents this debris on the happy path. This cleans up what never took it.

Constraints

  • Never delete a branch and never push a deletion. Not local, not remote, not "the obviously safe ones", not when told to. The output is a command string.
  • Never remove or unlock a worktree. Propose it; the user runs it.
  • Do not push the rescue branch. Hand it to land.
  • Do not trust git branch --merged or git cherry in a squash repo — both report merged branches as unmerged. Merge evidence is the PR list.
  • Zero commits ahead is a complete answer. Do not read content to confirm what rev-list already settled.
  • State the limits in the report: only squash-merge GitHub was validated, and rung 2 depends on gh.
  • Rung 4 is the user's call, not yours. Present the evidence and the question; do not decide what the repo considers worth keeping.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.