Ce Commit Push Pr

Git Commit, Push, and PR

Asking the user: When this skill says "ask the user", use the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_question in Antigravity CLI (agy), ask_user in Pi (requires the pi-ask-user extension). Fall back to presenting the question in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

Mode

• Description-only — user wants just a description ("write/draft a PR description", "describe this PR", or pasted a PR URL/number alone). Run Step 4 only; print the result. Apply only if the user asks. If a PR ref was pasted, pass it to Step 4 so Pre-A resolves the right range.
• Description update — user wants to refresh/rewrite an existing PR's description with no commit/push intent. If no open PR, report and stop. Otherwise run Step 4 (PR mode using the existing PR's URL), then Step 5 to preview, confirm, and apply via gh pr edit.
• Full workflow — otherwise. Run Steps 1-5 in order.

Context

On platforms other than Claude Code, run the Context fallback below. In Claude Code, the labeled sections contain pre-populated data — use them directly.

Git status: !git status

Working tree diff: !git diff HEAD

Current branch: !git branch --show-current

Recent commits: !git log --oneline -10

Remote default branch: !git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'

Existing PR check: !gh pr view --json url,title,state 2>/dev/null || echo 'NO_OPEN_PR'

Context fallback

printf '=== STATUS ===\n'; git status; printf '\n=== DIFF ===\n'; git diff HEAD; printf '\n=== BRANCH ===\n'; git branch --show-current; printf '\n=== LOG ===\n'; git log --oneline -10; printf '\n=== DEFAULT_BRANCH ===\n'; git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'; printf '\n=== PR_CHECK ===\n'; gh pr view --json url,title,state 2>/dev/null || echo 'NO_OPEN_PR'

---

Step 1: Resolve branch and PR state

The remote default branch returns something like origin/main; strip the origin/ prefix. If it returned DEFAULT_BRANCH_UNRESOLVED or bare HEAD, try gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'. If both fail, fall back to main.

Branch routing:

• Detached HEAD — explain a branch is required and ask whether to create a feature branch. If yes, derive a name from the change content. If no, stop.
• On default branch with work to do (uncommitted, unpushed, or no upstream) — automatically create a feature branch (pushing the default directly is not supported). Derive a name from the change content and continue at Step 3, which handles branch creation safely. Do not ask whether to branch — committing on the default is not an option here.
• On default branch with no work — report no feature branch work and stop.
• Feature branch — continue.

Note the existing PR URL from the PR check if state: OPEN. Step 5 uses it to route between new-PR and existing-PR application.

Step 2: Determine conventions

Match repo style for commit messages and PR titles (project instructions in context > recent commits > conventional commits as default). With conventional commits, default to fix: over feat: when ambiguous — adding code to remedy broken or missing behavior is fix:. Reserve feat: for capabilities the user could not previously accomplish. The user may override.

Step 3: Commit and push

If on the default branch, branch creation needs to handle stale local <base>, unpushed commits on local <base>, and uncommitted changes that collide with the fresh remote base. Read references/branch-creation.md and follow its decision flow before continuing.

Scan changed files for naturally distinct concerns. If they clearly group into separate logical changes, create separate commits (2-3 max). Group at file level only — no git add -p. When ambiguous, one commit is fine.

Stage and commit each group. Avoid `git add -A` and `git add .` — they sweep in .env, build artifacts, and generated files:

git add file1 file2 file3 && git commit -m "$(cat <<'EOF'
commit message here
EOF
)"

Then push:

git push -u origin HEAD

If the working tree is clean and all commits are already pushed, this step is a no-op.

Step 4: Compose the PR title and body

You MUST read `references/pr-description-writing.md` in full — the core principle at the top governs every step. The only input it needs from this skill is the PR ref, if one was identified by mode dispatch (description-only with a pasted URL, or description update).

Evidence decision before composition. CE no longer owns a dedicated capture workflow; modern harnesses provide their own browser, screenshot, terminal recording, and artifact capture tools. Treat evidence as user-supplied context or as validation prose, not as a separate skill dispatch.

1. User supplied evidence (URL, markdown image/embed, local artifact path they want referenced) — incorporate it into the PR body as ## Demo, ## Screenshots, or ## Evidence, matching the artifact type. Do not invent or upload evidence. 2. User explicitly asks to include evidence but has not supplied it — ask for the URL/markdown/path, or tell them to use the current harness's capture flow and return with the artifact. Do not launch another CE skill. 3. Agent judgment on authored changes — if you authored the commits and know the change is non-observable (internal plumbing, type-only, backend refactor without user-facing effect, docs/markdown/changelog/CI/test-only, pure refactors), skip evidence handling without asking.

Otherwise, if the branch diff changes observable behavior (UI, CLI output, API behavior with runnable code, generated artifacts, workflow output), include a concise validation note in the PR body describing what was exercised and how it behaved. If no real run was possible because of unavailable credentials, paid services, deploy-only infrastructure, hardware, or missing local setup, say that plainly in the validation section.

Do not block PR creation solely because no visual artifact exists. Test output and manual validation notes are acceptable validation evidence, but do not label test output as "Demo" or "Screenshots."

Then continue with the rest of the reference (Steps A through G) to compose the title and body.

Step 5: Apply and report

Description-only mode — print the title and body. Stop unless the user asks to apply.

New PR (full workflow, no existing PR from Step 1) — apply per "Applying via gh" below using gh pr create. Report the URL.

Existing PR (full workflow, found in Step 1) — the new commits are already on the PR from Step 3. Report the PR URL, then ask whether to rewrite the description.

• No — done.
• Yes — run Step 4 if not already done, then preview and apply (see below).

Description update mode, or existing-PR rewrite confirmed — preview before applying. Ask: "New title: <title> (<N> chars). Summary leads with: <first two sentences>. Total body: <L> lines. Apply?" If declined, the user may pass focus text back for a regenerate; do not apply. If confirmed, apply per "Applying via gh" below using gh pr edit and report the URL.

---

Applying via gh

The body must be written to a temp file and passed via --body-file <path>. Never use --body-file -, stdin pipes, heredoc-to-stdin, or --body "$(cat ...)" — wrappers and stdin handling can silently produce an empty PR body while gh still exits 0 and returns a URL.

BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/ce-pr-body.XXXXXX") && cat > "$BODY_FILE" <<'__CE_PR_BODY_END__'
<the composed body markdown goes here, verbatim>
__CE_PR_BODY_END__

The quoted sentinel keeps $VAR, backticks, and any literal EOF inside the body from being expanded.

For <TITLE>: substitute verbatim. If it contains ", ` `, $, or \`, escape them or switch to single quotes.

gh pr create --title "<TITLE>" --body-file "$BODY_FILE"   # new PR
gh pr edit   --title "<TITLE>" --body-file "$BODY_FILE"   # existing PR

Branch creation from default branch

Local <base> may have stale commits (another session/worktree advanced it) or commits the user authored intending to branch from later. Local git can't distinguish these — ask when unpushed commits are present.

Decision flow

1. Fetch fresh remote base

git fetch --no-tags origin <base>

If fetch fails (network, auth, no remote), use the fallback at the bottom.

2. Check for unpushed local commits on <base>

git log origin/<base>..HEAD --oneline

• Empty output: set BASE_REF=origin/<base> and proceed to step 3.
• Non-empty output: show the commit list and ask (per the "Asking the user" convention in SKILL.md):

"Local <base> has N unpushed commits not on origin/<base>. Carry them onto the new feature branch, or leave them on local <base>?"

• Carry forward → BASE_REF=HEAD. The new branch starts from local HEAD, preserving the commits.
• Leave on `<base>` → BASE_REF=origin/<base>. The new branch starts clean; commits remain on local <base>.

Never default silently — carrying foreign commits into a PR is worse than asking again.

3. Create the feature branch

git checkout -b <branch-name> "$BASE_REF"

If checkout fails because uncommitted changes would be overwritten, stash and retry:

git stash push -u -m "ce-commit-push-pr: pre-branch <branch-name>"
git checkout -b <branch-name> "$BASE_REF"
git stash pop

If git stash pop reports conflicts, surface the conflict output and the stash ref to the user — do not auto-resolve.

Fetch failure fallback

If git fetch fails, branch from current local HEAD:

git checkout -b <branch-name>

Note in the user-facing summary that base freshness was not verified. Skip the unpushed-commits check — without a fresh origin/<base>, the answer is unreliable.

PR Description Writing

The core principle

The diff is already visible on GitHub. The description exists to explain what the diff cannot show: what was impossible before and is now possible, what was broken and is now fixed, what shape changed. Cut any sentence a reader could reconstruct from the diff itself.

• Bad: "Adds evidence-decider.ts, modifies ce-commit-push-pr/SKILL.md to call it, and updates two test files."
• Good: "Evidence capture now decides automatically whether a change has observable behavior. CLI tools and libraries are now eligible alongside web UIs."

If the lead sentence describes what was moved, renamed, or added rather than what's now possible or fixed, rewrite it. This applies to every section, not just the opening — restating the diff is the failure mode this skill exists to prevent.

For user-facing bugs, run an extra before/after pass before writing the mechanism: name what the user would have seen before and what they now see instead. Only then mention the technical cause or fix, and only if it helps the reviewer understand risk. A lead like "Playback hooks now ignore late async responses" is still too mechanical if the visible bug was "old videos, thumbnails, or errors could appear after switching selections."

---

Step Pre-A: Resolve the range and base

Two modes:

• Current-branch mode (default) — describe HEAD vs the repo's default base.
• PR mode — describe a specific PR. Triggered when the caller passes a PR ref.

For PR mode, fetch metadata first:

gh pr view <ref> --json baseRefName,headRefOid,url,body,state,isCrossRepository,headRepositoryOwner

If state is not OPEN, report and stop — do not invent a description. Use baseRefName as <base> and headRefOid as <head>.

For current-branch mode, resolve <base> in priority order: caller-supplied (base:<ref>) → git rev-parse --abbrev-ref origin/HEAD (strip origin/) → gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' → try main/master/develop via git rev-parse --verify origin/<candidate>. If none resolve, ask the user. <head> is HEAD.

Base remote: origin for current-branch mode and same-repo PRs. For fork PRs, match the PR's base owner/repo against git remote -v. If no local remote matches, skip to the gh fallback — do not diff against origin (wrong base).

git fetch --no-tags <base-remote> <base>
git fetch --no-tags <base-remote> <head>   # PR mode only: <head> is headRefOid and may not be local
git log  --oneline "<base-remote>/<base>..<head>"
git diff           "<base-remote>/<base>...<head>"

If the commit list is empty, report "No commits to describe" and stop.

Fallback — use gh pr diff <ref> and gh pr view <ref> --json commits when local git can't reach the refs (fork PR with no matching remote, shallow clone, offline, merge-base on unrelated histories). For GHES configurations that reject SHA fetch but allow refs/pull/:

git fetch --no-tags <base-remote> "refs/pull/<number>/head"
PR_HEAD_SHA=$(awk '/refs\/pull\/[0-9]+\/head/ {print $1; exit}' "$(git rev-parse --git-dir)/FETCH_HEAD")

Note in the user-facing summary when the API fallback was used.

---

Step A: Size the description

Match weight to weight. When in doubt, shorter wins. Subtract fix-up commits (review fixes, lint, rebase resolutions) when sizing — they're invisible to the reader. Large PRs need more selectivity, not more content.

For small + simple PRs, the value-led sentence is the entire description. For small + non-trivial bugfixes, the 3-5 sentence target still needs a user-visible before/after lead when the bug affected UI, CLI output, workflow output, or any other user-observable behavior. Concision is not a reason to skip the visible symptom.

---

Step B: Compose the title

type: description or type(scope): description.

• Type by intent, not file extension. When fix and feat both seem to fit, default to fix — adding code to remedy missing behavior is fix. Reserve feat for capabilities the user could not previously accomplish. Use refactor/docs/chore/perf/test when more precise.
• Scope (optional): narrowest useful label. Omit when no single label adds clarity.
• Description: imperative, lowercase, under 72 chars, no trailing period.
• Match repo conventions visible in recent commits.
• Never use `!` or `BREAKING CHANGE:` without explicit user confirmation — they trigger automated major-version bumps.

---

Step C: Assemble the body

In order: opening → body sections that earn their keep → test plan if non-obvious → evidence block if one exists → Compound Engineering badge after a --- rule.

The opening goes under ## Summary if the body uses any ## headings; bare paragraph otherwise. No orphaned opening paragraphs above the first heading.

Evidence handling: preserve any existing ## Demo or ## Screenshots block verbatim unless the user's focus asks to refresh it. If the caller passed a freshly captured URL or path, splice as ## Demo. Otherwise omit. Place before the badge. Never label test output as "Demo" or "Screenshots."

Visual aids: reach for a diagram or table when it conveys the change faster than prose — relationships, flows, state transitions, sequences, trade-offs, before/after data, or any structure prose would have to enumerate. Mermaid and markdown tables cover most shapes; don't be limited to a particular type if a different one fits the change better. Place inline at the point of relevance. Skip for simple, prose-clear, or rename/dep-bump changes. Prose is authoritative when it conflicts with a visual.

GitHub gotchas: never prefix list items with # (GitHub auto-links #1 as an issue ref). Use org/repo#123 or full URL for actual references.

---

Step D: Badge

---

[![Compound Engineering](https://img.shields.io/badge/Built_with-Compound_Engineering-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
![HARNESS](https://img.shields.io/badge/MODEL_SLUG-COLOR?logo=LOGO&logoColor=white)

Model slug: spaces become underscores; append context window and thinking level in parens if known. URL-encode literal parens as `%28` / `%29` — unencoded parens inside markdown image URLs break release-please's commit parser, which silently drops the commit from the changelog. Examples: Opus_4.6_%281M,_Extended_Thinking%29, Sonnet_4.6_%28200K%29, Gemini_3.1_Pro.

Skip the badge if regenerating a body that already contains it.