# Branch Inspector > Inspect one git branch vs main: overview of commits, diff, merge/PR status, staleness; user picks delete/archive/PR/keep; emit action plan. Use for 'review this branch', 'branch cleanup'. Skip for repo audits, multi-branch sweeps, PR code review. - Skill: `montimage/branch-inspector` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add montimage/branch-inspector` - Raw SKILL.md: https://api.skillmd.com/api/skills/montimage/branch-inspector/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Montimage (https://skillmd.com/u/montimage) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/montimage/branch-inspector --- # Branch Inspector Inspects a single git branch against `main` to support a cleanup decision. The skill produces a deep overview of what the branch contains, surfaces signals that inform the keep/delete/archive/PR decision, asks the user to choose, then emits a concrete action plan for the chosen path. ## When to use - The user is cleaning up branches and wants to understand one before acting on it. - The user names a specific branch ("look at `feature/foo`", "is `experiment/x` worth keeping?"). - The user wants a deep summary of what a branch implements before deciding its fate. Do **not** use this skill for: scanning many branches at once, full repo audits, or reviewing a PR diff line-by-line. ## Inputs The branch name is passed as an argument. If the user invokes the skill without one, ask which branch to inspect — do not default to the current branch silently. The branch may be local (`feature/foo`), remote (`origin/feature/foo`), or both. Detect which exist and report both states. ## Prerequisites Verify before running. Stop and tell the user if any check fails. - Current directory is a git repository (`git rev-parse --git-dir` succeeds). - `main` branch exists locally or on `origin` (`git rev-parse --verify main` or `origin/main`). If the project's primary branch is `master` or something else, ask the user to confirm the comparison base. - The target branch exists locally or on `origin`. If neither, stop and tell the user. - `gh` CLI is optional; used to detect linked PRs. If not available, skip the PR-check step rather than failing. ## Repo Sync Before Inspect (mandatory) Inspection is read-only on the working tree but needs fresh refs to be accurate. Before inspecting: ```bash git fetch origin --prune ``` `--prune` removes stale remote-tracking refs so the skill doesn't report a branch as "exists on remote" when it was deleted upstream. Do not check out the branch and do not modify the working tree during inspection. ## Workflow ### 1. Resolve the branch Given the branch name, determine: - Does it exist locally? (`git rev-parse --verify `) - Does it exist on remote? (`git rev-parse --verify origin/`) - Are local and remote in sync, or has one diverged from the other? Pick the inspection target: prefer the local ref if both exist and are in sync, otherwise inspect each side separately and call out the divergence. ### 2. Build the overview Collect signals across five groups: **identity & activity, merge status, diff scope, implementation depth, staleness**. Run independent git commands in parallel where possible. See `references/overview-fields.md` for the exact field list, the git commands per field, and how to use `git cherry` for squash-merge detection. The implementation-depth group is the one that matters most for the decision — go beyond stats and read the diff to explain what the branch does. If the diff is too large to read in full, spawn an Explore subagent rather than skimming superficially. ### 3. Present the overview Output a structured report. Use this template: ``` ◆ Branch Overview: ·································································· Refs: local= remote= in-sync= Tip: by Diverged at: Activity: commits ahead, commits behind main last commit days ago Authors: Diff: files, +/- lines Top areas: , , Merge status: cherry-equivalent: / commits already on main Linked PR: Conflict risk: Staleness: 30d) | abandoned (>90d)> Intent: What this branch implements: <2-6 sentences describing the actual change, drawn from the diff> Notable findings: - - - Recommendation: Reasoning: ``` The recommendation is a suggestion, not a decision. Always defer to the user. ### 4. Ask the user to decide Present four options explicitly: 1. **Delete** — branch is obsolete, already merged, or abandoned with nothing worth saving. 2. **Archive** — preserve the work but get it out of the active branch list. 3. **Open a PR** — branch is ready or close to ready for review. 4. **Keep** — branch is still in active development; no action now. Ask the user which path to take. Do not act until they answer. If the user picks **Archive**, follow up with: "Tag-and-delete (`archive/` tag, then delete branch) or rename to `archive/`?" Do not assume. ### 5. Emit the action plan Once the user has decided, output a numbered action plan with the exact commands. Do **not** execute them automatically — this is a cleanup workflow and the user should run the commands themselves or explicitly approve. See `references/action-plans.md` for the four plan templates (delete, archive tag-and-delete, archive rename, open PR, keep). Pick the template matching the user's decision, substitute ``, and present the numbered steps to the user. For the PR template, fill in the title and body from the implementation summary built in step 2. ### 6. Stop The skill emits the plan and stops. Executing destructive commands (`branch -D`, `push --delete`) is the user's call, not the skill's. If the user explicitly asks the skill to run the plan, confirm once before each destructive step. ## Step Completion Reports Emit a report after the overview phase and after the plan phase. ``` ◆ Branch Overview (step 1 of 2 — ) ·································································· Refs resolved: √ pass Merge status: √ pass Diff analyzed: √ pass Implementation: √ pass (deep read) PR check: √ pass (or — gh CLI not available) ____________________________ Result: PASS ``` ``` ◆ Action Plan (step 2 of 2 — decision: ) ·································································· Decision captured: √ pass Plan emitted: √ pass Commands listed: √ pass ____________________________ Result: PASS ``` ## Expected output A complete run produces three artifacts in the chat, in order: 1. **Branch Overview block** matching the template in step 3 (refs, tip, activity, diff, merge status, linked PR, conflict risk, staleness, intent, "What this branch implements" prose, notable findings, recommendation). 2. **Decision prompt** listing all four options (delete / archive / open PR / keep). For archive, a follow-up prompt asking tag-and-delete vs rename. 3. **Action plan** — the numbered template from `references/action-plans.md` matching the user's choice, with `` substituted and (for PR) suggested title/body filled in. See `references/example-output.md` for a worked example showing the overview block, decision prompt, and follow-up plan for an archived branch. ## Acceptance criteria A run is correct when **all** of these hold: - The skill ran `git fetch origin --prune` before reading any refs. - The branch was resolved on both local and remote; divergence (if any) was reported. - The Overview block contains every field listed in the step 3 template, with no `` left unfilled. - Merge status was determined using `git cherry main ` (squash-detection), not just `git branch --merged`. - The "What this branch implements" prose is grounded in the actual diff — it names files, modules, or functions that appear in `git diff main...`. - All four decision options were presented; if archive was chosen, the tag-vs-rename follow-up was asked. - The emitted action plan matches `references/action-plans.md` for the chosen decision, with `` substituted. - No destructive command (`branch -D`, `push --delete`, `tag`) was executed by the skill itself. ## Edge cases - **No `main` branch.** Repos using `master`, `develop`, or `trunk` — ask once and use the answer for the rest of the run. - **Branch only exists on remote.** Inspect `origin/` directly; do not check out locally. - **Branch only exists locally.** Note "remote=no" and skip linked-PR check. - **Branch is identical to main.** Report 0 commits ahead and recommend delete. - **Branch is fully squash-merged.** `git branch --merged` says no but `git cherry` shows all `-` lines — recommend delete and call out the squash detection. - **Diff too large to read in full.** Spawn an Explore subagent to summarize rather than skimming superficially. Note in the overview that the summary is from a subagent. - **Detached HEAD or invalid name.** Stop and tell the user; do not guess. - **Active worktree on the branch.** Refuse the delete plan; tell the user to remove the worktree first. - **`gh` CLI not installed.** Skip the linked-PR check; mark as "n/a — gh not available". Do not fail the run. - **User refuses to choose.** Print the overview, note "decision deferred", and stop. ## Notes - **Read-only by default.** The skill never deletes, pushes, or rewrites refs on its own. It emits commands; the user runs them. - **Don't trust the branch name.** A branch called `fix/typo` may contain a refactor; always verify intent from the diff, not the name. - **Context budget.** For very large diffs, prefer an Explore subagent over reading the full diff in the main context window — summarized findings cost fewer tokens and keep the overview focused.