Create Pr

Generate Pull Request Description

Generate a short, narrative PR description that tells reviewers why this change exists and what to expect when they open the diff. Reviewers skim. If the description is long, they skip it. Respect their time.

Modes

Parse $ARGUMENTS. --split selects an alternate workflow. The pre-push quality step (Step 5.5) runs the full review + simplify works by default; the --no-* / --quick flags below scale it down. All flags compose with the default and split workflows.

| Mode / Flag | Trigger | Behaviour | | -------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | default | No flag | One PR for the whole branch. Step 5.5 runs the full polish pass (reviewer agent → simplify) via Skill("polish"). Follow Steps 1–10 below. | | split | --split, -s, or first positional token split | Analyse the branch diff, propose 2–4 dependency-ordered draft PRs (hard cap 5), execute only after user approval. Jump to the Split Mode section after Core Principles. | | no-review | --no-review | Step 5.5 drops the reviewer pass → Skill("polish", "simplify") (simplify only). | | no-simplify | --no-simplify | Step 5.5 drops the simplify pass → Skill("polish", "review") (reviewer only). | | quick | --quick | Step 5.5 runs only the light mechanical pass → Skill("polish", "quick") (no reviewer agent, no structural refactors). | | no-quality | --no-quality anywhere in arguments | Skip the Step 5.5 pre-push quality pass entirely and the Step 6.5 post-push feedback loop. Wins over every other quality flag. | | no-feedback | --no-feedback anywhere in arguments | Skip the default-on post-push reviewer-feedback loop (Step 6.5). Composes with everything. |

The pre-push quality step is a thin delegation to the [polish](../../quality/polish/SKILL.md) skill — see Step 5.5 for the full flag-to-mode mapping and precedence.

> Legacy positive flags. --review and --simplify are still accepted as explicit single-pass scoping: --review alone ≡ --no-simplify (reviewer only), --simplify alone ≡ --no-review (simplify only), and --review --simplify ≡ the default (full). Prefer the --no-* form — with the full pass now the default, the negative flags read more clearly.

The post-push reviewer-feedback loop (Step 6.5) is ON by default. After the PR is created, a background subagent runs /implement-suggestion --watch, which waits for the repo's review bots (Claude, CodeRabbit, …) and humans to comment, applies the actionable feedback, pushes, and repeats until the reviewers go quiet (max 5 iterations). It runs in parallel with the CI watch (Steps 7–9). Pass --no-feedback to skip it. On repos with no review automation it ends quietly after the first wait, so the default is safe.

In split mode, skip Step 5's "PR too big" trim — the split is the response to that signal. Each resulting sub-PR must still pass it on its own. With --split, run the resolved polish pass once on the full branch before computing the split (i.e. run Step 5.5 before S1), so each sub-PR inherits the cleaned-up code.

Length budget — the hard rule

A reviewer should read the entire description in under 30 seconds. Concretely:

• Body target: ≤ 25 rendered lines. Hard ceiling: 40. Tables, checklists, and blank lines all count toward this.
• Why: 1–2 sentences. Not paragraphs.
• What changed: 2–4 bullets, one line each. No sub-bullets, no code blocks inside bullets.
• How to verify: ≤ 3 lines. Prefer a single command over prose.
• Notes for reviewers: optional. If present, ≤ 2 sentences. Move implementation detail into code comments or PR review threads, not the body.

If you can't fit the change inside this budget, the PR is probably too big — stop and offer the user /create-pr --split instead of expanding the description.

Core Principles

1. Narrative over checklist. Reads like prose explaining a decision, not a bullet-point manifest of every file touched.
2. Why first, then what, then how to verify. Motivation drives understanding. A reviewer should be able to predict the diff after reading the description.
3. Group by concept, not by file. Don't enumerate every changed file — describe the ideas the change introduces.
4. No filler. Skip empty checklists, stock "Code follows guidelines" boxes, and boilerplate that adds noise without information.
5. One line per bullet. If a bullet wants a follow-up clause, it's two changes — split or cut the second.

Step 1: Gather Information

Run these in parallel:

git branch --show-current
git log main..HEAD --oneline
git diff main...HEAD --name-status
git diff main...HEAD --stat
git diff main...HEAD              # full diff — needed to understand intent

Also check for a PR template:

# Common template locations (check all)
ls .github/pull_request_template.md \
   .github/PULL_REQUEST_TEMPLATE.md \
   .github/PULL_REQUEST_TEMPLATE/ \
   docs/pull_request_template.md \
   PULL_REQUEST_TEMPLATE.md 2>/dev/null

Step 2: Understand the Narrative

Before writing anything, answer these questions for yourself by reading the diff:

• What problem or goal motivated this change? (the why)
• What is the core idea of the solution? (one sentence — the headline)
• What are the 2–4 conceptual moves the diff makes? (not files — concepts)
• What should a reviewer pay extra attention to? (risk areas, judgment calls, follow-ups)
• How was it verified? (tests added, manual checks, scenarios covered)

If you can't answer these from the diff alone, ask the user — don't pad the description with guesses.

Step 3: Choose Output Format

Branch A — Repository has a PR template: Use it. Fill each section with the narrative version (short, focused, no filler). Leave optional sections empty rather than padding with N/A boilerplate. Keep checkbox lists if the template has them, but only check what genuinely applies.

Branch B — No PR template: Use the lean default below. Do not invent extra sections.

Lean default (when no template exists)

## Why

[1–2 sentences. The problem or user-visible outcome. Link the issue if there is one. Don't restate the title.]

## What changed

- [Conceptual change 1 — one line]
- [Conceptual change 2 — one line]
- [Conceptual change 3 — one line]

## How to verify

- [Single test command or one scenario, one line]

## Notes for reviewers

[Optional, ≤ 2 sentences. Skip this section entirely if there's nothing load-bearing to flag.]

Aim for 2–4 bullets under "What changed". If you have 6+, the PR is too big or you're enumerating files instead of concepts.

Step 4: Write the Title

• Imperative mood, specific, under ~70 chars.
• Follow Conventional Commits if the repo uses them: type(scope): brief description.
• Good: fix(auth): refresh token when API returns 401
• Bad: Bug fix, Various improvements, feat: stuff

Step 5: Length self-check (before pushing)

Count the rendered lines of the body. If it's over 25, cut. Common cuts:

• Collapse "Notes for reviewers" unless it flags a real risk or judgment call. "We chose X because Y" usually belongs in a code comment.
• Drop "internal narration" — explanations of memo deps, useEffect timing, and other implementation detail that a reviewer will read in the diff anyway.
• Merge bullets that share a verb. "Added X. Added Y. Added Z." → one bullet listing the three.
• Cut "How to verify" prose — one command beats three sentences.
• Drop sub-bullets entirely. If a bullet needs a sub-bullet, split it into two top-level bullets or remove the detail.

If you've cut as much as you can and it's still over 40 lines, the PR is too big. Stop and offer the user /create-pr --split before pushing.

Step 5.5: Pre-push quality pass (delegated to polish)

Clean the branch before it goes up by delegating to the [polish](../../quality/polish/SKILL.md) skill. polish owns all the pre-push quality logic (the mechanical-fix criteria, the docstring R35 special case, the reviewer-agent dispatch, the simplify pass, and the commit-per-pass behaviour), so create-pr carries none of it — the two can never drift.

Skip this step entirely if any of the following hold:

• --no-quality was passed in $ARGUMENTS.
• The branch diff is non-code only (docs, generated artefacts, lockfiles, asset binaries). Decide from the file list, not the line count.

Otherwise, map the create-pr flags to a polish mode and invoke it once. The default is the full pass; the flags scale it down. Evaluate in this precedence order (first match wins):

| # | Flags present | Invoke | What runs | | - | ------------------------------------------------------ | ------------------------------- | ----------------------------------------------------- | | 1 | --quick, or both --no-review and --no-simplify | Skill('polish', 'quick') | Light mechanical pass (comments, naming, dead code). | | 2 | --no-review (or legacy --simplify alone) | Skill('polish', 'simplify') | code-quality simplify — apply Class M refactors. | | 3 | --no-simplify (or legacy --review alone) | Skill('polish', 'review') | Reviewer agent — auto-fix simple, plan complex. | | 4 | none of the above (default) | Skill('polish') | Full: review pass, then simplify pass. |

(--no-quality is handled above as an outright skip and never reaches this table.)

Pass --critical through to polish if the user passed it to create-pr.

polish operates on the same branch diff from Step 1, applies its fixes, and commits each pass as its own chore: commit — so create-pr does not commit here; polish already did.

After it returns, read its report:

• If polish surfaced planned-complex (reviewer) or Class J (simplify) proposals worth a reviewer's eye, append at most one bullet under "Notes for reviewers" naming the largest one. Don't enumerate every finding.
• If polish made no changes, continue silently.

Hard rules for this step (enforced inside polish, restated here as the contract):

• Never delete or weaken a test, never change public API / exported types as a mechanical fix.
• One polish invocation per PR creation. Don't loop.

Step 6: Push and Create Draft PR

git push                    # tracking already configured by gw add

gh pr create --draft \
  --title "" \
  --body "$(cat 
EOF
)"

Capture the PR URL/number from the output — the next steps need it.

Step 6.5: Dispatch the post-push reviewer-feedback loop (default ON)

After the PR exists, absorb whatever feedback the repo's review bots (Claude, CodeRabbit, …) and humans post — iteratively — without blocking the main thread.

Skip this step when --no-feedback (or --no-quality, which implies no automated feedback work) is in $ARGUMENTS. Otherwise run it for every create-pr.

Dispatch a subagent with run_in_background: true that drives the watch loop, and continue to Step 7 in the main thread immediately — do not block on it:

Agent(
  description: "Absorb PR review feedback (watch loop)",
  subagent_type: "general-purpose",
  run_in_background: true,
  prompt: |
    Drive the reviewer-feedback loop for PR  to completion.

    Invoke: Skill('implement-suggestion', ' --watch')

    That skill waits for new review-bot / human comments after each push,
    validates each through /critical + /confidence, applies the actionable
    ones, pushes, and repeats until the reviewers go quiet (max 5 iterations).
    It never opens a new PR and never undrafts this one.

    Return its final watch report verbatim: the per-iteration table, the
    stop reason, the head commit SHA, and any surfaced (needs-user) comments.
    Keep it under 150 words; do not paste comment bodies or diffs.
)

The watch loop and the main-thread CI watch (Steps 7–9) push to the same branch in parallel. Each downstream skill handles pull-rebase internally; do not add explicit serialisation.

Print one line before continuing:

Dispatched background reviewer-feedback loop (PR: ). Continuing with CI watch.

Step 7: Wait for CI to Settle

The job isn't done when the PR is created. Block on CI so the user doesn't have to come back to a red PR later.

sleep 10                                          # let workflows register
timeout 1800 gh pr checks  --watch     # blocks until every check completes (30-min cap); non-zero exit if any failed

--watch waits for queued/running checks and exits with the final aggregate status. If the exit code is 0, jump to Step 10. Otherwise continue.

The timeout 1800 cap keeps a hung or queued-forever check from blocking the skill indefinitely — same idea as the bounded poll in the watch loop ([../../workflow/implement-suggestion/rules/watch-mode.md](../../workflow/implement-suggestion/rules/watch-mode.md)). If it expires (exit code 124), run gh pr checks once, report the still-pending checks to the user, and escalate instead of re-watching.

If gh pr checks reports no checks at all after a minute, this repo probably doesn't run CI on PRs — also jump to Step 10.

Step 8: Triage Failures (delegate log-reading to subagents)

CI logs are huge and most of their content is irrelevant the moment you've classified the failure. Don't pull them into the main thread — fan out one general-purpose subagent per failed check. They run in parallel; each returns a short, structured summary.

Spawn one subagent per failed check, all in the same turn so they run concurrently:

description: Triage CI failure on 
subagent_type: general-purpose
prompt: |
  Read the failing GitHub Actions log and classify it. Do not fix anything — just report.

  Run: gh run view  --log-failed
  PR: 
  Check: 
  Diff context: this PR's branch is ; relevant files are .

  Return a report with exactly these fields:
  - failing_step: which job/step failed
  - error_excerpt: the 5–15 most relevant log lines, no more
  - category: one of [lint-format, generated-artifact, trivial-type, snapshot, real-test, ambiguous-type-or-build, unrelated-or-flake, infra-or-workflow, sensitive (auth/security/migration/data)]
  - suggested_fix: one sentence; if mechanical, name the exact command (e.g. `pnpm lint --fix`)
  - flake_suspected: true/false with one-line reason

  Keep the whole report under 200 words. Do not paste raw logs.

Use the returned category to decide the path:

• lint-format, generated-artifact, trivial-type, snapshot → mechanical, go to Step 9 auto-fix.
• real-test, ambiguous-type-or-build, infra-or-workflow, sensitive → judgment, go to Step 9 escalation.
• unrelated-or-flake (or flake_suspected: true) → re-run failed jobs once before treating

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mthines
• Source: mthines/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.