validate-branch-refs

name	validate-branch-refs
description	Use when checking a branch for drift before merge — references or claims a diff left stale: renamed/moved paths, removed exports, changed signatures, dropped env vars, dead doc links, outdated commands or version/port numbers. Triggers: "validate references", "check stale refs", "validate branch", "fix outdated docs", "/validate-branch-refs". Compares current branch vs base (default `dev`) and writes fixes.
argument-hint	[base-branch] [--dry-run] [--scope=docs|code|all] [--no-questions]
allowed-tools	["Read","Edit","Write","Bash","Glob","Grep","AskUserQuestion","Agent"]

Detect drift between the current branch and a base (default `dev`): find references in the working tree to anything the diff changed — renamed/moved paths, deleted or renamed exports, changed signatures, removed env vars, dead links, outdated commands — and fix them. Then validate factual claims the diff did NOT touch but may still be wrong (e.g. a doc says `port 3000` but config now says `4000`).

This skill writes edits — it is not read-only. Use --dry-run to preview.

Parse `$ARGUMENTS` literally; a flag is active only if its token appears.

• First non-flag token → base branch (default dev).
• --dry-run → report only; no writes, no commits.
• --scope=docs|code|all → limit the reference scan. docs = *.md/*.mdx/README*/CHANGELOG*; code = everything else; all = default.
• --no-questions → never prompt; log ambiguous findings as UNRESOLVED and continue.

1. `git rev-parse --is-inside-work-tree` is `true`, else abort. 2. `git rev-parse --verify ` succeeds (try `origin/`; if still missing, ask for the base). 3. If `git status --porcelain` is non-empty and not `--dry-run`, warn that uncommitted edits will mix with skill edits and ask whether to continue. 4. `MERGE_BASE=$(git merge-base HEAD )` — all diffs use `${MERGE_BASE}..HEAD`.

Phase 1 — Inventory the diff

In parallel:

• git diff --name-status ${MERGE_BASE}..HEAD → classify each path (A / D / M / R→rename / C).
• git diff ${MERGE_BASE}..HEAD -- '*.json' '*.yaml' '*.yml' '*.toml' '*.env*' → config drift.
• git log ${MERGE_BASE}..HEAD --format='%H %s' → commit context.

Build a table: change_type | old_path | new_path | symbols_removed | symbols_renamed | values_changed. For modified source files, pull removed/renamed top-level symbols from git diff -U0 (lines matching ^-(export|function|class|const|type|interface), language-aware: ts/tsx/js/jsx/py/go/rs/rb). For config files, diff changed keys (jq for JSON, plain diff otherwise).

Phase 2 — Reference scan

For each inventory row, git grep -nI the current tree (skips binaries, respects .gitignore) for:

• Paths — old path, basename, and extensionless form.
• Symbols — removed/renamed identifiers, word-boundary matched.
• Config values — old values of changed keys (env names, ports, URLs, versions).
• Commands — if package.json scripts / Makefile targets changed, their old names in docs.
• Links — for renamed docs, old relative links and anchor slugs.

Exclude the changed files themselves and node_modules/, dist/, build/, .next/, coverage/, .git/. Honor --scope.

Phase 3 — Classify each hit

Produce findings: id | file:line | reference | inventory_row | proposed_fix | confidence.

• high — unambiguous rename/move, or a symbol renamed with a single definition.
• medium — a similarly-named symbol still exists, or multiple move candidates match.
• low — a Phase 4 claim that maps to no diff row.

Phase 4 — Claim validation (independent of the diff)

Scan docs (README*, docs/**, *.md, *.mdx) for claims regardless of the diff:

• backticked file paths → exist on disk?
• repo-internal anchors → anchor exists?
• env vars (process.env.X, ${X}, bash fences) → defined somewhere (.env.example, config, code)?
• pnpm / npm run / yarn scripts → exist in the nearest package.json?
• ports, version pins → match config/package files?
• quoted signatures or types → symbol still has that shape?

Each failure is a low-confidence finding.

Phase 5 — Resolution

In confidence order (high → medium → low):

• high, not --dry-run → apply Edit and log it.
• medium / low → AskUserQuestion with file:line, the reference, candidate fixes, and Skip / "mark UNRESOLVED" / "intentional" options. Under --no-questions, mark UNRESOLVED.

Batch related questions (same symbol or renamed path) into one multiSelect call. Cap at 8 AskUserQuestion calls per run; mark the remainder UNRESOLVED.

Phase 6 — Report

Write .claude/skills/validate-branch-refs/last-run.md (only add it to .gitignore on explicit user opt-in) with the inventory table, per-finding outcome (APPLIED / SKIPPED / UNRESOLVED + reason), and counts. Then print a compact chat summary:

Branch: <head> vs <base> (merge-base <short-sha>)
Inventory: <n> files (<A>A <D>D <M>M <R>R)
Findings: <total> (high <h>, medium <m>, low <l>)
Outcome: applied <a>, skipped <s>, unresolved <u>
Report: .claude/skills/validate-branch-refs/last-run.md

Never auto-commit — the user reviews and commits.

- Edit only — never delete files, never push or touch the base branch. - A fix that would change semantics (not just a reference) → downgrade to medium and ask. - If a target file is already user-modified (`git status`), ask before stacking an edit on it. - On any `git` failure, surface stderr and abort the phase — don't continue silently. - On failure, report the error clearly and leave no half-applied edits. If the inventory exceeds ~50 changed files or the scan yields ~200+ hits, delegate Phases 2–3 to a `general-purpose` subagent (inventory table embedded in the prompt; it returns the findings table). Keep Phase 5 resolution on the main thread to preserve `AskUserQuestion` control.