git-strategy-advisor

Use when deciding git workflow strategy for planned or completed work. Recommends branch creation vs direct commit, branch naming, push timing, and PR creation based on change scope and type.

SKILL.md

GitHub

Git Strategy Advisor

Lightweight nudge for non-routine git decisions: branch or commit-on-main, push now or wait, PR or direct merge. Advisory only — never executes. For routine commits, the model should skip this skill and just commit.

Session-scope discipline is enforced structurally by the session-scope-guard PreToolUse hook (~/.claude/hooks/session-scope-guard.py), which refuses bulk-stage patterns (-A, ., -u) and refuses commits whose staged paths weren't modified this session. This skill assumes the hook is in place; if you're operating without it, follow the session-scope rule below manually.

When to Use

  • A non-trivial feature is about to begin and you're unsure of the branch model
  • Implementation is far enough along that "how do I integrate this?" isn't obvious
  • The work spans multiple files and you want a quick sanity check on push/PR scope

When NOT to Use

  • Routine single-commit fixes — just commit
  • Executing the commit/push — use /commit-commands:commit or /commit-commands:commit-push-pr
  • Final integration decision after work is fully done — use superpowers:finishing-a-development-branch
  • Creating an isolated workspace — use superpowers:using-git-worktrees
  • Anything where the hook needs to be bypassed (escalate to the user, don't silently set SESSION_SCOPE_BYPASS)

Session-scope rule (one line)

Stage only paths this session modified. Never git add -A / . / -u. Flag dirty paths Claude didn't touch — don't include them. The session-scope-guard hook will reject violations regardless.

Heuristic table

Walk top-down; the first matching row wins.

Situation Recommendation
≤3 files, <100 lines, on main, solo Commit + push directly to main
Many files, one topic, on main, solo Commit + push to main; consider a branch only if main is shared with collaborators or CI is sensitive
Multi-topic dirty tree Split into logical commits, then push each
WIP across multiple sessions, not ready to ship Create a feature/ branch, push to back up work, no PR yet
Feature complete, want review or to track in a PR Branch + push + open PR
Out-of-session files dirty Flag them in the response; do NOT include them. The hook will block if you try.

Branch naming (when a branch is the answer)

{type}/{2-4-word-description}, lowercased, hyphen-separated, ≤40 chars. Type prefix:

  • fix/ if the work fixes a bug
  • refactor/ if the work restructures without changing behavior
  • docs/ if documentation-only
  • feature/ otherwise

Output shape

When this skill is invoked, respond with this terse block (no YAML schema, no confidence calibration, no warnings array):

Recommendation: <commit + push to main | branch + push | branch + push + PR | review-only>
Stage:          <path/a, path/b, ...>  (or "none — out-of-session changes only")
Skip:           <out-of-session paths, if any>
Branch name:    <only if branching>
Commands:
  git add path/a path/b
  git commit -m "<one-line summary>"
  git push   (or `git push -u origin <branch>` if new branch)
  (optional: gh pr create --fill if PR)

If the session set is empty AND the working tree is dirty, recommendation is review-only and the commands section is omitted.

Worked example

Session has modified src/foo.py and tests/test_foo.py. git status also shows an untracked notes.md that no tool call touched.

Recommendation: commit + push to main
Stage:          src/foo.py, tests/test_foo.py
Skip:           notes.md (out-of-session, untracked)
Commands:
  git add src/foo.py tests/test_foo.py
  git commit -m "<one-line summary>"
  git push

Notes

  • The hook is the structural guarantee; this skill is the brief advisory layer on top.
  • If you need to bypass the hook intentionally (rare — e.g., committing files generated by a sub-agent you explicitly trust), escalate to the user before setting SESSION_SCOPE_BYPASS=1. Do not bypass silently.
  • This skill does not delegate to other skills. It is a leaf node.