agent-pr-authoring

name	agent-pr-authoring
description	Author a pull request an AI coding agent can actually get merged: a scoped, coherent diff; a Summary and Test Plan backed by real evidence; correct triage of required-and-blocking CI gates versus external/advisory checks (e.g. a Cloudflare Pages preview build); draft-while-WIP discipline; named fixup commits for real review findings; and a clean landing through a merge queue without force-pushing or bypassing branch protection. Use when opening, updating, triaging red CI on, or landing an agent-authored GitHub PR. NOT for this repo's internal release ceremony, actor embodiments, or contributor mirror-sync mechanics (use port-daddy-internal-dev), tracking backlog/issue lifecycle across a board (use agent-issue-tracker-workflow), or deciding what to build next / sequencing a roadmap (use legible-roadmap-with-sidequests).
license	Apache-2.0
allowed-tools	Read,Write,Edit,Bash,Grep,Glob
metadata	{"category":"Agent & Orchestration","tags":["pull-request","ci-gates","code-review","merge-queue","github-agent-workflow"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"agent-work-receipt-designer","reason":"A receipt's diffSummary and artifact-backed validation are exactly what a real Test Plan should contain."},{"skill":"agent-issue-tracker-workflow","reason":"Tracks the work item a PR closes; this skill covers landing the PR itself, not the backlog lifecycle around it."},{"skill":"port-daddy-internal-dev","reason":"Supplies this repo's specific release ceremony and mirror-sync rules that sit on top of the general PR mechanics here."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}

Agent PR Authoring

Get an agent-authored change through review and landed, without a giant diff, an evidence-free Test Plan, or a gate-confusion incident.

Use This For

• Scoping a coding agent's change into one reviewable PR before opening it.
• Writing a ## Summary and ## Test Plan with real commands and observed output, not a claim.
• Triaging red CI: separating a real required gate (lint, tests, roadmap-link, pr-requirements-guard) from an external, non-blocking check (a Cloudflare Pages preview build).
• Running draft-while-iterating, marking ready only when the real gates are green, and processing bot/human review as named fixup commits.
• Landing through a merge queue: enqueue, let the queue pick the strategy, rebase and recheck when the base moves — never force-push, never --admin past a real gate.

Do Not Use This For

• This repo's specific release ceremony, internal actor embodiments, or skill-mirror sync mechanics (port-daddy-internal-dev).
• Tracking a backlog item's lifecycle across a board or issue tracker (agent-issue-tracker-workflow).
• Deciding what to build next or sequencing a roadmap of side-quests (legible-roadmap-with-sidequests).

Process

flowchart TD
  A[Scope one reviewable diff] --> B[Draft Summary + evidence-backed Test Plan]
  B --> C[Open PR as draft]
  C --> D[Push commits, CI runs]
  D --> E{Gate triage}
  E -->|Real required gate red| F[Fix root cause]
  F --> D
  E -->|External check red| G[Note it, do not block on it]
  E -->|All required gates green| H[Mark PR ready]
  H --> I[Review arrives: bot + human]
  I --> J[Fix HIGH findings as named fixups]
  J --> K[Rebase onto latest base]
  K --> L{Still mergeable?}
  L -->|No, base moved| K
  L -->|Yes| M[Enqueue in merge queue]
  M --> N[Queue applies its strategy and lands]

1. Scope the diff before opening it. One PR = one reviewable change. If the work mixes a refactor, a feature, and a dependency bump, split it into separate PRs even if that means three PRs instead of one.
2. Write the Summary and Test Plan together. Summary states what changed and why (and what it deliberately does not do). Test Plan lists the exact commands run and the observed output — a reviewer should be able to reproduce the claim without asking. "Tests pass" with no command or output is not a Test Plan.
3. Open as a draft while iterating. Draft signals "not yet reviewable"; push commits and let CI run until the real required gates are green before asking for review.