git-strategy-advisor

name	git-strategy-advisor
last_updated	"2026-05-24T00:00:00.000Z"
description	Use BEFORE starting a non-trivial feature OR after implementation when integration strategy is non-obvious — should this be a branch or direct commit? When to push? PR or direct merge? Triggers on "how should I structure this?", "branch or commit?", "ready to ship". Recommends staging ONLY files modified during the current session; the session-scope-guard PreToolUse hook enforces this structurally at commit time (independent of this skill). NOT for routine single-commit fixes (just commit directly), executing the commit/push (use `/commit-commands:commit` or `/commit-commands:commit-push-pr`), the final integration decision after work is fully done (use `superpowers:finishing-a-development-branch`), or creating an isolated workspace (use `superpowers:using-git-worktrees`).

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.