Subagent Driven Branch Ref Froze Stranded Commits

Diagnose and recover from "PR merged, but half my work is missing from main" cases in `superpowers:subagent-driven-development` (or similar one-fresh-subagent-per-task) sessions, where committed work survives in the worktree's `HEAD` chain but never makes it into the pushed branch ref. Use when ANY of these appears: (1) `gh pr view <N>` body claims "M files changed, N insertions" but `gh pr diff <N> --name-only | wc -l` returns a smaller number than you expect (canary: PR-body file count > actual squash-commit file count), (2) the merged squash commit on main is MISSING entire files you remember creating (Dockerfile, route handler, deploy artefact, etc.) — and you wrote AND committed them per the subagent reports, (3) `git rev-parse HEAD` ≠ `git rev-parse <feature-branch>` in the worktree (HEAD is ahead), (4) `git reflog show <feature-branch>` ends earlier than `git log --oneline` on the same worktree (reflog gap = stranded zone), (5) tests that passed locally during the session now fail on main because files referenced by the committed code never landed, (6) the receiving session (or human running CI) discovers `ModuleNotFoundError`, `sql_path missing`, or similar "file referenced by code does not exist" symptom on freshly-pulled main. Root cause: one of the implementer subagents committed in a detached-HEAD state (e.g., after a `git checkout <sha>`, post-stash, post-cherry-pick abort, or an internal worktree reset by a tool). Subsequent subagents inherit the detached HEAD; each `git commit` advances HEAD but never updates the named branch. `git log` (without an explicit ref) walks from HEAD, so every per-task diagnostic looked correct. `git push <branch>` ships the branch ref — i.e. the truncated tree. The squash captures only the truncated portion. Sister to `working-tree-edits-stranded-on-squash-merge` (uncommitted Edit() — different mechanism, same symptom class) and `pr-followup-commit-stranded-after-squash` (commits pushed after merge — different timing). Distinct from `pr-hijack-via-stale-worktree-branch-ref` (which is about overwriting a different branch upstream).

mkdir -p ~/.claude/skills/subagent-driven-branch-ref-froze-stranded-commits
curl -L https://claudskills.com/skills/subagent-driven-branch-ref-froze-stranded-commits/SKILL.md \
  -o ~/.claude/skills/subagent-driven-branch-ref-froze-stranded-commits/SKILL.md

@misc{subagent-driven-branch-ref-froze-stranded-commits-2026,
  author    = {Claude Code},
  title     = {Subagent Driven Branch Ref Froze Stranded Commits [Claude Code skill]},
  year      = {2026},
  publisher = {ClaudSkills},
  url       = {https://claudskills.com/skills/subagent-driven-branch-ref-froze-stranded-commits/}
}