Safe Git Ops

Help the user perform common Git operations without confusing sandbox failures, repository state issues, and real content conflicts.

Skill Directory Layout

<installed-skill-dir>/
├── SKILL.md
└── references/
    ├── failure-modes.md
    ├── commit-paths.md
    └── worktrees.md

Progressive Loading

• Always read references/failure-modes.md
• Read references/commit-paths.md when the user asks to commit, push, speed up closeout, or choose validation/reinstall scope
• Read references/worktrees.md when the repo uses git worktree, when .git points to another directory, or when the user mentions multiple worktrees

Core Behavior

• Separate preflight inspection from state-changing Git commands
• Distinguish sandbox or permission failures from merge conflicts
• Treat worktrees as a special case because they may write shared Git metadata outside the visible working directory
• Ask before destructive operations such as reset --hard, checkout --, deleting branches, or dropping stashes
• Prefer non-interactive Git commands
• Use risk-tiered commit paths so low-risk text/docs changes do not pay the cost of full validation, full smoke tests, or full skill reinstall
• Use sidecar-task-runner precommit classification for non-trivial closeouts when it can run read-only and reduce main-agent decision time
• When a write operation is blocked by the sandbox, explain that clearly and request escalation instead of guessing about conflicts
• When a network Git operation fails, distinguish network/sandbox access from authentication, Git remote, or repository problems before asking the user to change credentials
• Bias toward early activation: if the user reports a Git failure in vague language, assume this skill should own the diagnosis before any state-changing command runs

Trigger Heuristics

Use this skill immediately when any of these show up:

• the user asks to run git cherry-pick, merge, rebase, commit, stash, switch, checkout, branch, or worktree
• the user says "Git failed", "merge broke", "cherry-pick is blocked", "there is a conflict", or "why did this repo get into this state"
• the agent sees error text involving:
  • CONFLICT
  • index.lock
  • operation not permitted
  • permission denied
  • Could not resolve host
  • Could not read from remote repository
  • Connection timed out
  • Network is unreachable
  • .git/worktrees/
  • ORIG_HEAD
  • CHERRY_PICK_HEAD
  • branch is already checked out

Do not wait until after a failed write to load this skill if the task is obviously Git-heavy.

Misdiagnoses To Avoid

Never say any of the following unless Git actually proved it:

• "this is a merge conflict" when the error is really permission-related
• "this is just local to the current worktree" when the common git dir may be involved
• "Git is broken" when the real issue is dirty state, detached HEAD, or an in-progress operation
• "your token/SSH key/remote is broken" when the first failure is a sandboxed network or DNS failure
• "just rerun it" without saying whether the block is conflict, repo state, or sandbox

Step 1 — Orient the Repository

Before any meaningful Git action, inspect the repository shape:

git rev-parse --show-toplevel
git rev-parse --git-dir
git branch --show-current
git status --short

If the user mentions worktrees or .git is a file rather than a directory, also inspect:

git worktree list
git rev-parse --git-common-dir

Summarize:

• repo root
• current branch
• whether the tree is dirty
• whether this is a worktree
• whether shared Git metadata lives outside the current directory

Step 2 — Classify the Requested Operation

Handle the request as one of these categories:

• inspect: status, log, diff, branch list, remotes, worktree layout
• network_inspect: fetch, pull, push dry checks, ls-remote, submodule update, or any Git operation that contacts a Git remote
• safe_write: add, commit, cherry-pick, merge, rebase, stash, branch creation, worktree creation
• destructive_write: reset, checkout over local changes, clean, branch deletion, stash drop, force push

For inspect, run the command directly if sandbox rules allow it.

For network_inspect, expect sandboxed runtimes to block DNS or outbound connections unless network permission is granted.

For safe_write, do a preflight check first. For commit/push closeouts, classify the change as Fast Path, Skill Path, Code Path, or Risk Path using references/commit-paths.md, then run the smallest validation set that matches the path.

For destructive_write, require explicit user confirmation before executing.

Step 3 — Preflight Before Any State-Changing Git Command

Before safe_write or destructive_write, gather enough context to avoid sloppy failure handling:

git status --short
git branch --show-current
git rev-parse --short HEAD

For ordinary commit/push closeout, avoid full orientation unless Risk Path applies. A Fast Path closeout may use only git status --short, git diff --check, explicit git add <files>, and git diff --cached --stat before commit.

For cherry-pick, merge, or rebase, also inspect the target commit or branch first:

git log --oneline --decorate -n 5
git show --stat --summary <target>

For worktrees, inspect the shared metadata location:

git rev-parse --git-common-dir

If the command will likely write to shared Git metadata outside the sandboxed writable root, tell the user this before running it and be ready to request escalation.

If the user specifically asked for a worktree-scoped write operation such as cherry-pick, merge, or commit, explicitly mention before running it that worktrees may require writes under the common git dir rather than only the visible worktree path.

Step 4 — Execute and Interpret Failures Correctly

When a Git write fails, classify the failure before telling the user what happened.

Use the guidance in references/failure-modes.md. The high-level rule is:

• If Git reports CONFLICT, conflict markers, or asks to resolve files, this is a code conflict
• If Git reports operation not permitted, permission denied, failure to create lock files, or inability to update refs or worktree metadata, this is a sandbox or permission problem
• If Git reports DNS failure, API/host connection failure, timeout, or network unreachable during fetch, pull, push, ls-remote, or submodule operations, this is network/sandbox access until rerun with network permission
• If Git reports dirty state, untracked-file overwrite, detached HEAD mismatch, or missing commit, this is a repository state problem

Do not tell the user "there is a conflict" unless Git actually reported one.

Do not tell the user "authentication failed", "SSH key is wrong", or "the remote repo is missing" when Git never reached the host because of DNS/network/sandbox restrictions.

Step 5 — Escalate Cleanly When Sandbox Restrictions Are the Real Problem

If a write command is important and fails because of sandbox restrictions:

1. State that the failure is environmental, not a code conflict
2. Name the blocked operation
3. Mention the likely write target if known, such as:
   • .git/index.lock
   • .git/worktrees/...
   • shared refs under the common git dir
4. Request permission escalation and rerun the same command

Use wording like:

This git cherry-pick failure looks like a sandbox write restriction, not a merge conflict. Git needs to update shared worktree metadata, so I should rerun it with elevated permissions.

If a network Git command is important and fails because DNS, API, or host connection is blocked:

1. State that the first failure is network/sandbox access, not proven Git auth or remote configuration failure
2. Name the command, such as git fetch, git push, or git ls-remote
3. Request network permission and rerun the same command
4. Only after a network-enabled rerun should you classify credential, permission, missing-repo, branch, or server-side errors

Use wording like:

This git ls-remote failure did not reach GitHub; it looks like sandboxed network access, not a missing repo or bad SSH key. I should rerun it with network permission before diagnosing credentials.

Step 6 — Worktree-Specific Rules

When the repo uses worktrees:

• Assume commit, cherry-pick, merge, rebase, and similar commands may write outside the current worktree directory
• Check git worktree list and git rev-parse --git-common-dir early
• Avoid claiming that a failure is "local to this worktree" until you confirm where Git is trying to write
• Be extra careful with branch deletion or reset because another worktree may be using the same branch

Read references/worktrees.md for the detailed handling rules.

Step 7 — Report Outcomes Precisely

When you finish, report one of these outcomes clearly:

• success
• conflict requiring manual resolution
• sandbox or permission restriction
• network/sandbox restriction
• repository state problem that needs a user choice

For each case, give the user the next action, not a vague Git dump.

Good example:

git cherry-pick <commit> did not reach merge resolution. Git was blocked from writing shared worktree metadata under the common git dir, so this is a sandbox issue. The next step is to rerun the same command with elevated permissions.

Bad example:

cherry-pick failed, probably a conflict

Preferred Output Shape

When the user asked "what happened?" or "why did this fail?", report in this structure:

Operation: <git command>
Classification: success | content conflict | sandbox restriction | network/sandbox restriction | repository state problem
Evidence: <the key git message or state observation>
Why it happened: <short explanation>
Next step: <single concrete next action>

Keep the classification line explicit. That is the main protection against sloppy Git diagnoses.

Commands This Skill Should Handle Well

• git status, log, diff, show, branch, remote
• git fetch, pull, push, ls-remote
• git add, commit, stash
• git cherry-pick
• git merge
• git rebase
• git switch, checkout, checkout -b
• git worktree list, git worktree add

Commands Requiring Extra Caution

• git reset --hard
• git checkout -- <path>
• git clean -fd
• git branch -D
• git stash drop or clear
• git push --force

Do not run these without explicit user approval.