Git Strategy Advisor

---
name: git-strategy-advisor
last_updated: 2026-05-24
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.