Unfuck My Git State

Recover a repository without making the blast radius worse.

Core Rules

1. Snapshot first. Do not "just try stuff."
2. Write evidence only beneath the controller-assigned .agents/state/<task-slug>/ directory.
3. Resolve the per-worktree and common Git directories; never assume .git is a directory.
4. Prefer non-destructive fixes before force operations.
5. Inspect reflog and create rescue refs before moving a branch pointer.
6. Create and verify a metadata backup before any manual metadata edit.
7. Obtain point-of-risk confirmation for the exact target and values before a force or manual edit.
8. After each fix, run verification before proceeding.

Rule Ownership

This skill owns Git repair and broken-state recovery behavior. Public maintenance docs can point here, but recovery agents should load this skill before touching Git metadata, index files, worktree metadata, or refs.

• Use ordinary ls-git-merge-rebase for healthy advanced Git operations.
• Use this skill when Git commands report contradictory state, missing objects, broken index/cache-tree data, zero hashes, or stale worktree locks.
• Use the controller-assigned Git-bound task slug. Do not invent a second task-state directory.
• Do not execute destructive recovery commands while diagnosing or generating a plan.

Fast Workflow

Set the explicit private output boundary once:

TASK_STATE_DIR="$PWD/.agents/state/<controller-task-slug>"

1. Capture diagnostics beneath that directory:

python scripts/snapshot_git_state.py . --output-dir "$TASK_STATE_DIR"

2. Route by symptom using references/symptom-map.md.
3. Generate a plan from a new snapshot. The generator consumes the snapshot path through its JSON manifest rather than guessing the newest directory:

python scripts/guided_repair_plan.py --repo . --output-dir "$TASK_STATE_DIR"

4. Apply the smallest matching playbook.
5. Run the references/recovery-checklist.md verification gate.
6. Escalate only if the gate fails.

For an existing snapshot or explicit routing:

python scripts/guided_repair_plan.py --snapshot "$TASK_STATE_DIR/git-state-snapshots/<stamp>"
python scripts/guided_repair_plan.py --list
python scripts/guided_repair_plan.py --symptom phantom-branch-lock

Snapshot Evidence Contract

snapshot_git_state.py records:

• porcelain-v2 status and branch headers
• current branch and symbolic HEAD
• a resolvable HEAD^{commit} probe
• per-worktree and common Git directory paths
• worktree, refs, reflog, remote, and fsck diagnostics
• snapshot.json, binding the emitted snapshot path to the explicit task output directory

A detached-HEAD diagnosis requires all three signals: # branch.head (detached), an empty git symbolic-ref -q HEAD result, and a resolvable HEAD^{commit}. One signal alone is not enough.

Regression Harness

Use disposable simulations before changing script logic:

python scripts/regression_harness.py
python scripts/regression_harness.py --scenario detached-head

The harness creates temporary repositories and never runs force, reset, prune, metadata-edit, or deletion commands against a user repository.

Playbook A: Orphaned Worktree Metadata

Symptoms:

• git worktree list shows a path that no longer exists.
• Worktree entries include invalid or zero hashes.

Start non-destructively:

git worktree list --porcelain
git worktree prune -v
git worktree list --porcelain

If stale entries remain, resolve the shared metadata root:

git rev-parse --path-format=absolute --git-common-dir

Create a verified backup with scripts/backup_git_metadata.py. Then require explicit confirmation naming the exact stale path before removing anything beneath the resolved common Git directory.

Playbook B: Phantom Branch Lock

Symptoms:

• git branch -d or git branch -D fails with "already used by worktree".
• git worktree list disagrees with observed branch ownership.

git worktree list --porcelain

Find the worktree using that branch, switch that worktree to another branch or intentionally detach it, then retry the branch operation in the main repository. Treat stale ownership metadata as Playbook A; do not guess a .git/worktrees/... path.

Playbook C: Detached or Contradictory HEAD

For corroborated detached HEAD, preserve the current commit before switching:

git reflog --date=iso -n 20 HEAD
git branch rescue/$(date +%Y%m%d-%H%M%S) HEAD
git switch <known-good-branch>

For contradictory branch and symbolic-ref evidence, run the guided planner with --repo and --output-dir. It automatically creates and verifies a metadata archive before showing manual repair commands.

Playbook D: Missing or Broken Refs

Symptoms: unknown revision, not a valid object name, or cannot lock ref.

Inspect and preserve local history first:

git reflog --date=iso -n 50 HEAD
git show <local-only-tip>
git branch rescue/$(date +%Y%m%d-%H%M%S) <local-only-tip>
git show-ref --verify refs/heads/rescue/<timestamp>

Then fetch and verify the exact remote target:

git fetch --all --prune
git show-ref --verify refs/remotes/origin/<branch>
git rev-parse --verify refs/remotes/origin/<branch>^{commit}

git branch -f moves a branch pointer. Immediately before it, obtain explicit point-of-risk confirmation naming the repository, local branch, verified remote ref, and resolved commit. Only that confirmation authorizes:

git branch -f <branch> refs/remotes/origin/<branch>
git switch <branch>

Last Resort: Manual HEAD Repair

Resolve both metadata roots; linked worktrees have distinct values:

git rev-parse --path-format=absolute --git-dir
git rev-parse --path-format=absolute --git-common-dir

Create and verify the backup automatically:

python scripts/backup_git_metadata.py . --output-dir "$TASK_STATE_DIR"

The command archives the actual metadata directory or directories, verifies the required HEAD members, hashes the archive, and writes a JSON receipt. A failed or missing receipt blocks repair.

After checking the expected branch ref, obtain explicit point-of-risk confirmation naming the repository, expected branch, resolved ref, and backup receipt. Prefer:

git show-ref --verify refs/heads/<branch>
git symbolic-ref HEAD refs/heads/<branch>

If symbolic-ref cannot be used, obtain a second confirmation for the exact resolved per-worktree HEAD path. Use the fallback printed by guided_repair_plan.py; never write to a guessed .git/HEAD path. Immediately run the verification gate.

Verification Gate

Run references/recovery-checklist.md. Minimum bar:

• git status exits cleanly with no fatal errors.
• symbolic HEAD matches the intended branch, or detached state is intentional and corroborated.
• git worktree list --porcelain has no missing paths and no unexplained zero hashes.
• git fsck --no-reflogs --full has no new critical errors.
• every rescue ref and changed branch pointer resolves to the expected commit.

Escalation Path

1. Create a verified metadata archive with scripts/backup_git_metadata.py.
2. Clone fresh from the verified remote.
3. Recover unpushed work from rescue refs or reflog and cherry-pick into the fresh clone.
4. Document the failure mode and add a focused regression scenario.

Automation Hooks

Worktree tooling must enforce:

• explicit controller task-state output
• preflight snapshot and state validation
• per-worktree/common metadata path resolution
• verified backup before manual metadata repair
• post-operation verification
• hard stop on unresolved HEAD/ref inconsistency
• point-of-risk confirmation before destructive commands

Resources

• Symptom router: references/symptom-map.md
• Verification checklist: references/recovery-checklist.md
• Diagnostic snapshot script: scripts/snapshot_git_state.py
• Verified metadata backup: scripts/backup_git_metadata.py
• Guided plan generator: scripts/guided_repair_plan.py
• Disposable regression harness: scripts/regression_harness.py