git v0.5.0F

Immutable. This exact content never changes and is served at /api/v1/blob/433cac952bb2f874.

---
name: git
description: >
  Load when planning or about to git commit, branch, push, rebase, resolve a merge conflict, open PR, stack PRs (even when gh-stack drives the stack),
  or write/update the description of a Pull Request (PR),
  attach a screenshot or video to a PR, respond to review comments, review a PR, watch/babysit a PR's CI or reviews.
  Carries the user's git conventions and style you are expected to match. Load as early as possible, the moment git or GitHub work is anywhere in the chat's future.
license: MIT
argument-hint: "[commit|branch|pr|attach|rebase|review|watch]"
metadata:
  author: sherifabdlnaby
  version: "0.5.0"
---

# Git

Route first: each action's actual rules live in a `references/` file. Open the matching one before planning or acting; rules like commit grouping and branch naming shape the plan, so reading them late
means redoing it. Several actions, several references.

## Router

**Branches** (create, name, stack) -> [`references/branches.md`](references/branches.md) Switching branches, naming rules, ticket references, switching with a dirty tree, stacked PRs (conventions
here, mechanics via the gh-stack skill), the gh-stack/manual path probe, cascade conflicts and verification, manual restacking fallback (after merge, chain of 3+, mid-stack push), force-pushing.

**Committing** -> [`references/commits.md`](references/commits.md)
Pre-staging walk, file confirmation, message style, hook-failure handling, scoping, editor-free squash, empty commits.

**Pull Requests** (open, update) -> [`references/pull-requests.md`](references/pull-requests.md) Pre-flight survey, title format (including the stacked `[n/N]` marker), body skeleton and how to write
descriptions, `--attach` exists on create/edit/comment, when a screenshot or video is worth attaching, AI
footers, post-create flow, finishing PRs after `gh stack submit`, linking PRs, updating a body without clobbering it.

**Attach a screenshot or video** -> [`references/attach.md`](references/attach.md)
`--attach` on create/edit/comment, body-file placement, screenshot framing guidance.

**Responding to review comments** (on your own/target PR) -> [`references/review-responses.md`](references/review-responses.md) Classify the reviewer (automated bot/AI tool, an AI-disclosed agent
behind a human account, or a human), then fix / push back / escalate; in-thread replies, thread resolution, re-requesting review, batching a round into one GraphQL query and one aliased mutation,
where a PR stands.

**Rebasing, resolving conflicts** -> [`references/rebase.md`](references/rebase.md)
Conflict-time snapshot (`ORIG_HEAD`), force-with-lease, unconditional range-diff verification.
Stacked-PR restack mechanics and `--onto` (drop intermediate commits) live in [`references/branches.md`](references/branches.md), read that too.

**Reviewing someone else's PR** -> [`references/reviewing.md`](references/reviewing.md)
Procedure: gather context, check out locally, trace the change, deliver a summary and review guide.

**Watch a PR's CI and reviews** -> [`references/watch.md`](references/watch.md) The four verdicts, the three modes (green CI / green and quiet / reviews only), the cheap
sub-agent that runs the loop, the stale nudge. Uses `scripts/pr-watch.py`, never a sleep loop; its flags are in `references/watch-flags.md`.

**Draft PR that review bots ignore** -> [`references/watch.md`, Draft PRs and review bots](references/watch.md#draft-prs-and-review-bots)
`pr-watch.py flick`: a mechanical toggle to ready and back so Copilot, Bugbot, and their kind review a draft; chasing beyond it only on the user's word that a bot exists, with `--wip` on the title.

**Stuck CI check with no manual retry** -> [`references/commits.md`, Empty commits](references/commits.md#empty-commits)
The last-resort empty commit: when it beats retrying the check, and the zero-file-change guards that keep approvals alive.

## Always

**Disclose AI.** Anything posted on GitHub on the user's behalf (PR body, comment, issue, ticket update) carries an **AI footer**.
The PR-body template lives in [`references/pull-requests.md`](references/pull-requests.md);
the post templates, one per tier of human judgment behind the post (Agent Decided, Human Approved,
Human Guided), live in [AI Disclosure](#ai-disclosure) below.
Use them as verbatim as possible, do not write from memory.

**Reach for `gh` first.** Every GitHub action goes through the `gh` CLI; the GitHub MCP server is
the fallback for what `gh` cannot do.

**Parallelize read-only calls.** Batch independent read-only `git`/`gh` calls
(`status`, `diff`, `log`, `gh pr view/diff/checks`) into a single tool call; each
sequential read is a roundtrip for nothing. Mutating commands (`commit`, `push`,
`rebase`, `gh pr create/edit/merge`) stay sequential.

**Fewer round-trips, smaller payloads.** Batching is the first lever; these are the next four,
your call when a one-off is cheaper:

- **One wide fetch, many narrow reads.** Anything you'll consult more than once in a task (PR JSON, `gh stack view --json`, a review-thread query) goes to a temp file once, and each step reads its
  slice with `jq`. Re-fetch after anything you did that changes it (push, edit, reply, resolve); or if time passed and you've been idle, a snapshot is not a live view.
- **Ask for an answer, not a payload.** A count or a single field leaves as `--jq '.x'`; a yes/no leaves as an exit code (`git diff --quiet`, `git merge-base --is-ancestor`). JSON you read with your
  own eyes is a payload.
- **Same-shape mutations ride one request.** GraphQL aliases: every reply, resolve, or title edit of a round in one `gh api graphql`. Aliases fail independently, so read the per-alias `errors[].path`,
  not the exit code.
- **Bodies travel by file.** PR body or GraphQL query to a file, then `--body-file` / `-F query=@file`. (why: shell quoting eats backticks and `$`, and a file stays editable for the next update.) The
  disclosure guard refuses a body it cannot read from a file.

**Resolve once per session, reuse everywhere.** One line for all three:

```bash
gh repo view --json nameWithOwner,defaultBranchRef --jq '"repo  \(.nameWithOwner)\ntrunk \(.defaultBranchRef.name)"'; gh api user --jq '"user  \(.login)"'
```

Carry `<OWNER/REPO>`, `<trunk>` and `<GITHUB_USERNAME>` through the session from that.

**Voice** for everything public (commit messages, PR titles and bodies, comments, issues):

- Omit needless words. Concise sentences, no padding paragraphs.
- Emojis sparingly, only where one helps the reader catch something while glancing.
- NO em dashes in any public-facing text. Use commas, parentheses, or periods. (why: em dashes are a classic AI tell and repel readers.)
- No vague reaffirmations like "for accountability", "for performance", "for resiliency" unless that reason is already in the conversation. (why: invented justification misrepresents the change.)
- Dry, low-key humor.
- Don't overdo formatting. Keep it balanced. (why: visual noise crowds out the content.)
- A user-supplied Human Note is exempt: it goes in the PR body verbatim.

## AI Disclosure

Every post on the user's behalf (comment, reply, issue) ends with an AI footer: a `---`, then one
line copied verbatim from the templates below. The PR-**body** variants live in
[`references/pull-requests.md`](references/pull-requests.md) and follow the same rule.

Placeholders, the same in every footer:

- `<TOOL>`: the tool you're running as, e.g. Claude, Cursor.
- `<MODEL>`: the friendly name of the model you're running, e.g. `Opus 4.8`.
- `<GITHUB_USERNAME>`: resolve once per session with `gh api user --jq '.login'`.

### Picking the variant

The footer answers one question for whoever reads the post: how much human judgment stands behind
it? Judge the decisions the post carries, not the request that produced them. The two human tiers
carry a word grading the degree; picking it is your call.

**🤖 Agent Decided.** You chose the change, position, or wording. Nobody has vetted it.

```markdown
_<sub>🤖 Agent Decided: Posted by <TOOL> (<MODEL>) autonomously on behalf of @<GITHUB_USERNAME>.</sub>_
```

**🧍‍♂️👍 Human Approved (glanced | read | tested).** The user had the real thing in front of them and
said yes. The word grades how closely they looked: `glanced` is a fast yes, `tested` means they ran
it themselves. A yes on something they would have had to go open is 🤖.

```markdown
_<sub>🧍‍♂️👍 Human Approved (<glanced|read|tested>): Posted by <TOOL> (<MODEL>) on behalf of @<GITHUB_USERNAME>.</sub>_
```

**🤝 Human Guided (nudged | steered | dictated).** A back and forth on a technical decision happened,
and its outcome is in this post. The word grades how much came from them: `nudged` is one remark that
changed your direction, `dictated` is them naming exactly what to do.

```markdown
_<sub>🤝 Human Guided (<nudged|steered|dictated>): Posted by <TOOL> (<MODEL>) on behalf of @<GITHUB_USERNAME>.</sub>_
```

Still 🤖, however it feels:

- A task, however specific. "Fix the flaky test", "file an issue about X": naming what to work on is not deciding what it says.
- A rule the user wrote earlier, in a skill, in CLAUDE.md, in memory. Their instruction set is not a call on this post.
- Delegation. "Do whatever you think is best" is the opposite of direction.
- Approval from anyone but the user. The post goes out under their name, so the tier reports what they did.
- A Human Note. It is context in the body, not a decision about the change.
- A reply posted from a watch loop. The user was not in it.

Already 🤝, even though every word is yours:

- They approved a written plan and the post carries out what it named.
- They picked one of the options you laid out, or answered the question that settled the design.

**Late approval** upgrades a PR body, piggybacked on the next body edit rather than a round-trip of
its own; a posted comment or reply keeps the footer it went out with. The user's own GitHub approval
of the PR counts as approval.

**Direction does not reach what they never saw.** On a long run, a post about a part the user was
never in is 🤖, and a push after approval drops back to 🤖 once it changes what they endorsed.

**Understate, never overstate.** Torn between two tiers, or two words, take the lower one. A footer
claiming human judgment that never happened is the failure that matters.