unfuck-my-git-state

What This Skill Does

unfuck-my-git-state is a surgical, high-reliability recovery agent for Git repositories suffering from corruption, metadata inconsistencies, or broken worktree states. Unlike typical 'git reset --hard' approaches that risk data loss, this skill employs a staged, diagnostic-first methodology. It treats the .git/ directory as sensitive production data, mandating snapshots and validation gates before any corrective actions are performed. By integrating with OpenClaw’s execution environment, it automates the complex dance of querying porcelain outputs, interpreting reflogs, and managing internal state files that typically lead to 'cannot lock ref' or 'phantom worktree' errors.

Installation

Install the skill via the OpenClaw CLI: clawhub install openclaw/skills/skills/delorenj/unfuck-my-git-state Ensure you have the necessary repository permissions and that your environment includes the standard Git utility suite. Once installed, the skill automatically registers the scripts/ directory, allowing for immediate execution of the snapshot and recovery diagnostic tools.

Use Cases

This skill is designed for critical failure scenarios where standard Git commands fail. Use it when encountering:

• Phantom Worktree Locks: When git worktree list shows stale paths or the system refuses to delete branches because it believes they are checked out.
• Ref Inconsistencies: Instances where Git reports 'unknown revision' or 'not a valid object name', often following aborted rebases or partial power failures.
• Detached HEAD Contradictions: When HEAD state becomes unreadable or contradicts existing branch markers.
• Missing Refs: Repairing zero-hash references (00000000...) that often cause repository bloat or fatal synchronization errors.

Example Prompts

1. 'My repository is reporting an orphaned worktree in /tmp/build-dir that I cannot remove; please run the diagnostic repair plan and clean it up.'
2. 'I’m getting a "cannot lock ref" error on my main branch. Run a snapshot, check the reflog, and identify the safest way to restore the pointer.'
3. 'Help, I have a detached HEAD and the branch list is blank. Use the guided repair plan to reattach to a rescue branch without losing my recent local commits.'

Tips & Limitations

• Safety First: Always run the provided snapshot_git_state.sh before attempting any fix. The agent is configured to abort if a snapshot fails to write.
• Local-Only: This skill is optimized for local repository corruption. It does not perform remote repository repair; it assumes you are working within a cloned environment.
• Escalation: If the recovery checklist fails after a fix, do not manually force the .git/ files. Use the regression harness to simulate potential fixes on a backup before reapplying them to your working directory.