Create Pull Request

Write a short, narrative PR description that tells reviewers why the change exists and what to expect in the diff, open it as a draft, converge it, and watch CI.

Contents

• Modes
• Step 0: Resolve your GitHub access path
• Steps 1–5: Write the title and body
• Step 5.5: Pre-push branch convergence
• Step 6: Push and Create Draft PR
• Step 6.2: Attach media
• Step 6.4: UI verification spec
• Step 6.5: Post-draft quality loop
• Step 7: Wait for CI · Step 8: Red CI · Step 10: Report
• Split Mode · Anti-patterns

Modes

Parse $ARGUMENTS. --split selects an alternate workflow; the other flags scale down the default full review + simplify loop (Step 6.5) and compose with both workflows.

rules/legacy-flags.md — read when $ARGUMENTS carries --review, --simplify, --pre-review, --no-feedback, or --no-preview-spec.

Step 0: Resolve your GitHub access path

Before any GitHub step, resolve which path you have — gh CLI, mcp__github__* tools, or neither — per agents/shared/rules/github-access.md. Resolve once, state the path you took, and use it for the whole run.

gh is absent in Claude Code cloud sessions; the commands below are the gh-path form, so on the MCP path use that file's verb mapping. With neither path, say so precisely, do the git work you can, and hand the rest back — never report a step you could not perform as blocked-by-something-else.

Steps 1–5: Write the title and body (shared contract)

Follow rules/description-contract.md (gather information → understand the narrative → choose output format → write the title → length self-check); review-loop uses the same contract. If its Step 5 length self-check says the PR is too big, offer /create-pr --split instead of expanding the body. If you can't infer the why / what from the diff, ask the user — never pad with guesses. Worked examples: rules/description-examples.md.

Step 5.5: Pre-push branch convergence (local review-loop)

Runs by default, in both default and split mode; skip on --no-pre-review, --no-quality, --no-review, or a non-code diff. review-loop with no PR reference runs local mode: it dispatches branch-reviewer with zero GitHub calls, so the draft opens already converged.

rules/pre-push-review.md — read when entering this step (skip conditions, handling each return, the outcome value for Step 10). Load-bearing:

• Surface every flagged finding to the user before pushing.
• Absent sub-agent dispatch is NOT REVIEWED, never a skip.
• Record the outcome now, before continuing. Step 10's slot for it is mandatory on every run.

Step 6: Push and Create Draft PR

Open the PR as a draft so pr-reviewer can post inline comments during Step 6.5.

git push                    # tracking already configured by gw add

gh pr create --draft \
  --title "<imperative title>" \
  --body "$(cat <<'EOF'
<your narrative description>
EOF
)"

Capture the PR URL/number from the output.

Step 6.2: Attach screenshots and recordings (delegated to attach-media)

Skip on --no-media. Otherwise rules/attach-media-step.md — read now: it selects up to 6 images and 2 videos (--attach files, then this branch's captures newer than the merge base) and delegates to Skill("attach-media", "<pr-url> <file>#<alt> ... --to body"). Record its first report line for Step 10. Never write a media placeholder.

Step 6.4: Author the UI verification spec (default ON for UI changes)

Skip this step when --no-ui-verify or --no-quality is in $ARGUMENTS, or when ui-verify is not installed (Skill() raises — catch, log one line, continue).

Do not eyeball the diff to decide whether it is UI: ui-verify author decides mechanically with its shared is-ui-diff gate and returns not authored (no UI files in diff) for a non-UI diff. So delegate unconditionally when neither skip condition holds:

Skill("ui-verify", "author <pr-url>")

ui-verify edits the PR body in place, adding one <!-- ui-verify:v2 --> block; the block is exempt from the length budget and preserved by the review-loop's description refresh (description contract). Continue to Step 6.5 regardless. This step only authors; Step 6.5's review-loop runs the spec against the preview once at exit (do not pass --no-preview-run).

Record which branch you took, now, before continuing. Write down exactly one of the six values for the Step 10 UI verify slot:

Never soften the last row into a skip: a failed return means no block exists for any later reader to run.

Step 6.5: Post-draft quality loop (delegated to review-loop)

Skip entirely on --no-quality, --no-post-review, or a non-code-only diff (docs, generated artefacts, lockfiles, asset binaries). Otherwise evaluate in this precedence order (first match wins):

Pass --critical through to review-loop / pr-reviewer if the user passed it. Always pass --no-ci to review-loop here — Steps 7–8 own CI for this invocation and cover every commit the loop pushes.

Rows 3 and 4 both need sub-agent dispatch. Before taking either row, confirm that some available tool dispatches a sub-agent — a capability check, never a tool-name check (Task in Claude Code, Agent in the Agent SDK, task in OpenCode-based hosts such as Dash0 Agent0). If none does, do not attempt the dispatch and do not fall through to row 2 — record NOT REVIEWED (sub-agent dispatch unavailable) for Step 10.

After the loop returns:

• Converged → continue to Step 7. The loop already refreshed the PR description; do not re-edit the body.
• Cap hit with threads still open → surface them to the user before Step 7.
• Loop returned a skip → the PR has not been reviewed. Continue, carrying NOT REVIEWED into Step 10 verbatim; never describe the PR as converged, clean, or review-ready.

Never delete or weaken a test or change public API / exported types as a mechanical fix. One review-loop invocation per PR creation. There is no background external-bot watch; a later reviewer is picked up by the next review-loop run or by /implement-suggestion <pr> --watch run on purpose.

Step 7: Wait for CI to Settle

Block on CI so the user doesn't come back to a red PR. Two harness facts govern this step:

1. Issue each watch call with the Bash tool's timeout parameter explicitly set to 600000. The default is 120 000 ms; without it the call is killed at 2 minutes with no exit code, whatever the inner timeout.
2. gh pr checks exits non-zero (8) while checks are merely pending. Classify on the exit code plus a literal stderr match, never on "was there output".

Step 7a: wait for checks to register

Run the shared poll — rules/registration-poll.md — and map its outcomes:

Step 7b: watch to completion

# Issue this Bash call with the tool parameter timeout: 600000.
# 540 < 600 so `timeout` fires first and yields a real exit 124.
timeout 540 gh pr checks <pr-number> --watch

Print ci-watch attempt N/4 (or registration poll N/3) as you make each attempt and carry the lines into Step 10. Increment before comparing. Both caps are local to this invocation; there is no shared counter across skills or sub-agents.

Step 8: Hand red CI to ci-auto-fix

A check genuinely failed. Invoke once:

Skill("ci-auto-fix", "<pr-url>")   → fixed | still-failing | escalated, with its report

ci-auto-fix owns the whole failure path (grouping, log reading, flake rerun, fix, local verify, push, re-verify); add no triage fan-out or /confidence pass of your own around it.

Cap: 2 invocations per create-pr run. Invoke a second time only when the first returned fixed and a different check went red on the pushed revision; never re-invoke on a check the first gave up on. Print ci-auto-fix invocation N/2 as you make each one.

Never do these to make CI green:

• Disable, skip, or set continue-on-error on a failing check
• Delete or weaken tests, lint rules, or type checks
• Push with --no-verify or otherwise skip hooks
• Mark the PR ready-for-review while checks are red

Step 10: Report

Short summary: final check status, one line per auto-fix, and anything left for the user (only if Step 8 escalated or hit the cap).

PR: <pr-url>
Title: <imperative title>

Pre-push review (Step 5.5, local review-loop): <converged (<N> iterations, <A> applied, <D> declined) | flagged (<G> findings) | cap-reached (<O> open) | checks-red (<checks>) | skipped (<flag>) | skipped (non-code diff) | NOT REVIEWED (sub-agent dispatch unavailable; fallback: <polish simplify | none>)>

Media (Step 6.2): <the attach-media summary line | none (no captures or --attach files) | none (merge base unresolved) | skipped (--no-media) | skipped (attach-media not available)>

UI verify (Step 6.4): <authored (<N> specs) | not authored (no UI files in diff) | skipped (--no-ui-verify) | skipped (--no-quality) | skipped (ui-verify not available) | failed (<reason>)>

Review loop (review-loop / pr-reviewer):
  Iterations: <N> of <cap>
  Stop reason: <all-threads-resolved | no-progress (flags remain) | cap-reached | skipped (--no-quality) | skipped (--no-post-review) | NOT REVIEWED (sub-agent dispatch unavailable)>
  Open threads at exit: <count>
  Description refreshed: <yes | unchanged | skipped>
  Final verdict: <PASS | FAIL>

CI:
  Watch attempts: <the `ci-watch attempt N/4` lines you printed, or "none needed">
  Final status: <green | which checks red>
  Auto-fixed: <one line per fix, or "none">
  ci-auto-fix: <the `ci-auto-fix invocation N/2` lines you printed, or "not needed">

Head commit: <sha — the head CI was last verified on>

The UI verify line is mandatory on every run, including a non-UI diff — not authored (no UI files in diff) is the informative answer there, not silence. The Pre-push review line is mandatory on every run too, including every skipped one; when it is flagged, list every flagged finding underneath. Why these slots exist: references/design-rationale.md.

Split Mode (--split)

rules/split-mode.md — read when --split is set, before Step 1. It defines how split mode changes Steps 1–5.5, then Steps S1–S8 (analyse, group, detect dependencies, propose and wait for approval, execute, watch CI bottom-up, rollback, report) and the split-mode hard rules.

Anti-patterns to Avoid

• Listing every file changed. Describe ideas, not paths.
• Restating the title in the summary.
• Padded checklists. Only checkboxes from a real template, checked only when they apply.
• Strings of unrelated features ("adds X, Y, Z and also…") — suggest splitting.
• Narrating the process ("First I tried X…"). Reviewers want the result.
• Vague verbs ("improved", "enhanced", "updated"). Say what changed and why it's better.
• Media placeholders. Never TODO: add screenshots, an empty <!-- screenshots -->, or a local .agent/ path in the body.
• Co-Authored-By lines. Never include Co-Authored-By: Claude or any AI co-author attribution.
• Prefer linking (Closes #123) over re-explaining context already in the issue.