ready-for-review

name	ready-for-review
description	Pre-handoff gate: runs verification, code review, syncs or opens a PR. TRIGGER when: handing off to a human reviewer — wrapping up a branch with an open PR, "ship it" intent, or before spawning a multi-persona review (CISO + staff-* engineers) or /ultrareview. DO NOT TRIGGER when: during active iteration, on diff-only requests, or on the default branch.
argument-hint	[optional PR context]

Ready-for-review gate

Run steps in order. Halt on failures unless the step is marked warn only. After fixes produced by step 3, re-run step 2 — do not re-run step 3 on its own output.

0. Activate gate session

Write the active-session marker so this skill's own iteration pushes (step 3 fix → push → loop back to step 2) are not self-blocked by the require-ready-for-review.sh hook:

~/.claude/scripts/marker.sh activate ready-for-review

If the chain fails (empty SESSION_ID), the capture-session-id.sh SessionStart hook didn't run — abort and report; the gate will block iteration pushes without this marker.

1. Preconditions (halt on fail)

• Current branch is not the default branch (main / master / develop).
• Working tree is clean: no unstaged or uncommitted changes.
• If a PR exists for the branch, capture its number and base: gh pr view --json number,baseRefName
• If no PR exists, step 5 will open one after verification and review.
• Branch is in sync with origin/<base>. Run the canonical detection recipe (see git-feature-branch-sync/SKILL.md § "Detecting divergence"). If behind > 0, invoke /git-feature-branch-sync, then re-run step 2 against the synced tree; step 8's completion marker must record the post-resync HEAD SHA so it matches what the push-gate hook checks.

2. Verification (halt on fail)

If the repo's CLAUDE.md has a Testing or Verification section, use those commands. Otherwise inspect the config (package.json, pyproject.toml, go.mod, Cargo.toml, Makefile, CI workflows) to identify the project's test, lint, and typecheck commands. Do not invent — skip undefined steps.

Run the checks inline — per subagent-delegation/SKILL.md § "Heavy command output — run inline".

Scope exceptions — skip step 2 entirely: skip when the diff contains no executable code — only markdown, plans, or non-executable config. Examples: skill bodies under .claude/skills/**, plans under .claude/plans/**, agent configs under .claude/agents/**, top-level *.md, docs/**. If the diff touches scripts, hooks, tests, or application source — even alongside docs — run step 2.

Pre-existing failures: if a step fails on code unrelated to this diff, confirm it's unrelated (git log -- <file>, git diff origin/<base> -- <file>), then either wait for the existing owner or open a separate branch. Rebase once the default branch is green.

Test-to-fit is forbidden: fix the code, not the test — unless the product requirement genuinely changed.

3. Code review (halt on findings)

Run /code-review against the cumulative PR-vs-default-branch diff — not staged changes, not per-commit deltas:

BASE_REF=$(gh pr view --json baseRefName --jq .baseRefName 2>/dev/null || echo main)
git diff $(git merge-base origin/$BASE_REF HEAD)...HEAD

The squash-merge artifact reviewers see is this diff; cumulative review surfaces cross-commit findings that per-commit review misses. Per-commit /code-review during iteration remains valuable — treat its findings as inputs here, not substitutes.

Because the reviewed diff is not the staged diff, do NOT write the review-completion marker (per /code-review's own rule). If findings are produced, fix them in a new commit; that commit goes through the normal staged-diff /code-review + marker gate, then return to step 2 and re-run fast checks. Do not re-run /code-review on its own output (loop risk).

Unskippable — markdown, skill, and config diffs benefit from the same pass.

4. Sync PR description (warn + fix; skip if no PR)

Invoke the sync-pr-description skill via the Skill tool against this branch's PR. It compares the body against branch state, verifies content claims, preserves coordination steps, and applies the fix with gh pr edit. Warn + fix; skip only if no PR exists. Unskippable when a PR exists — markdown, skill, and config diffs benefit from the same pass.

5. Create PR if missing (skip if PR already exists)

Skip if PR found in step 1. Halt if no remote tracking — "Branch is not pushed. Push with git push -u origin <branch> then re-run." TICKET-ID: split branch on /; if first segment matches ^[A-Za-z]+-[0-9]+$, use as title prefix; else omit. Title: <TICKET-ID>: <slug-hyphens-as-spaces> ≤70 chars. Body (omit $ARGUMENTS if empty; use single-quoted <<'EOF' heredoc; capture PR number for step 6). If /code-review returned a ## Deferred review findings block at review time (≥1 DEFER, no open PR), assign it to DEFERRED_FINDINGS and it will be spliced in above; otherwise set DEFERRED_FINDINGS to empty string:

## Summary
$(git log $(git merge-base origin/$(gh pr view --json baseRefName --jq .baseRefName 2>/dev/null || echo main) HEAD)..HEAD --format="- %s")
$ARGUMENTS
## Test plan
- [ ] (fill in manual verification steps)
$DEFERRED_FINDINGS
🤖 Generated with [Claude Code](https://claude.com/claude-code)

6. Final hygiene recheck (halt on fail)

Steps 3 and 4 may have produced new commits or body edits. Reconfirm:

• Working tree is clean.
• All commits are pushed. If git status shows the branch ahead of origin/<branch> because steps 2/3 produced fix commits, push them now — those commits are inside the approved scope of this gate and the user does not need to re-authorize the push. After pushing, re-verify the branch is no longer ahead.
• PR body edit (if any) landed — re-fetch with gh pr view and confirm.
• Branch is not behind the base branch — if steps 3–5 produced new commits, re-run the divergence detection recipe (git-feature-branch-sync/SKILL.md § "Detecting divergence") before handing off.

7. CI status (warn only)

Run gh pr checks <n>:

• All green → continue.
• Still running → note the in-flight checks; user decides whether to wait.
• No checks reported (gh pr checks exits non-zero) → not yet registered; treat as pending.
• Red → surface failing check names with a one-line summary of each. Do not auto-halt — sometimes the human reviewer wants to see the failure themselves — but make the failure explicit before handoff.

8. Record gate completion + deactivate session

If every halt-on-fail step above passed, record the completed gate and remove the active-session marker:

~/.claude/scripts/marker.sh write ready-for-review

Then remove the active-session marker:

~/.claude/scripts/marker.sh deactivate ready-for-review

Removes only this session's file. If the skill errors before reaching this step, the gate will evict the orphan automatically once the session's process ends — the hook checks PID liveness on each gate hit.

Do NOT write the completion marker if:

• Any halt-on-fail step (1, 2, 3, 6) produced findings that weren't fixed in this session.
• The user asked you to present findings without finishing the gate.
• You are not in a git repository.
• The branch has no PR and no remote tracking (nothing to gate).

Completion

Summarize for the user, then (and only then) signal that the branch is ready for human review:

• Verification: commands run and their results.
• Code review: findings fixed, or "none."
• PR description: sections updated, or "already in sync" / "no PR."
• CI: status per check.
• Branch: clean, pushed, PR #N ready for review.