--- name: pr-authoring description: "Playbook for deployment-aware pull requests — the 11-section format that turns a PR into a reviewable contract; why, decision requested, change map, review order, evidence, verification, risk, rollback. Used for the Define→build handoff and any PR a great-pm-driven project opens." --- ## Codex host binding - Treat references to Claude slash workflows as the equivalently named Codex skill. - Before delegating to any specialist, read the `great-pm-runtime` skill and the selected packaged role file. - Treat "invoke", "assign", "delegate", "spawn", and source Agent-tool instructions as a required Codex `spawn_agent` call with that role and a bounded assignment. - For the spawn tool's `task_name` or `agent_name` identifier, replace canonical role-name hyphens with underscores (`query-refiner-pm` → `query_refiner_pm`). Keep canonical names unchanged in prompts, filenames, verdict logs, and user-facing output; this is an internal identifier mapping, not a role rename. - Store every returned agent identifier. Never call a wait tool until a spawn has returned an identifier, and wait only on identifiers returned by successful spawns. - If `spawn_agent` is unavailable or a spawn fails, report BLOCKED; do not impersonate the specialist or wait on an empty agent set. - Resolve bundled paths from the installed GreatPM plugin root. - Ignore Claude-only model aliases, colors, turn limits, and tool allowlists. - Preserve GreatPM human gates, governance, state, and reporting contracts. # PR Authoring — playbook A PR is a contract with the reviewer, exactly as a PRD is a contract with engineering. The reviewer must understand what happened, what they are approving, what could go wrong, and how to undo it — **without opening the diff or the chat history**. Format adopted 2026-07-22 from the Symphony engineering-handoff pattern (ajayd942/cloudflare-ai-event-concierge#4). Related contracts: `ticket-authoring` (the upstream ticket this PR closes — its acceptance criteria become this PR's evidence rows) and `pr-review` (what the reviewer owes back). The full chain: PRD story → ticket → PR → review → merge → deploy. When starting a new product repo, copy `.github/PULL_REQUEST_TEMPLATE.md` from great-pm into that repo's `.github/` so GitHub auto-fills every new PR with this skeleton. ## 1. Required sections (in order) 1. **Reviewer summary** — three subsections: **Why** (the gap this PR addresses), **Outcome** (what it delivers), **Out of scope** (what it deliberately does NOT include — code, secrets, deployment, config). 2. **Decision requested** — exactly what approving means, what happens after merge, and what approval does **NOT** authorize. 3. **Tracking and design context** — links to the tracker issue, the upstream approved artifacts (PRD, strategy doc, ADRs), and the decision IDs this change traces to. 4. **Change map** — table: Area | What changed | Why it changed. 5. **Suggested review order** — table: Step | File or artifact | What to verify. Ordered by risk, highest first. 6. **Acceptance criteria and evidence** — table: Criterion | Implementation | Evidence. Every criterion from the spec maps to proof. 7. **Verification performed** — table: Check | Result. Real commands and real output, not "tested locally". Screenshot/video for UI changes; an explicit "not applicable because…" otherwise. 8. **Risk and impact** — table over five fixed dimensions: Security, Privacy/data, Cost, Operations/observability, Compatibility. "No change" is a valid entry but must be stated, never implied by omission. 9. **Limitations and follow-up** — what this PR honestly does not solve, and the follow-up issues filed for it. 10. **Rollback** — the exact undo path BOTH before merge (close the PR) and after merge (revert commit + what to verify). "No rollback applies" must be justified, never assumed. 11. **Handoff checklist** — the checkbox list from the template, checked only after actually doing each check. ## 2. Rules - **The title states the outcome, not the activity.** "Define the event concierge product requirements", not "Update docs". - **Decision requested is the deployment gate.** It must name what approval does NOT authorize (deployment, secret handling, spend, production config) — this is how the human stays the boss of the pipeline. - **Targets vs results honesty.** Every number is labeled either an approved target or a measured result. Claiming a target as a result is the fastest way to lose reviewer trust. - **Review order starts with the highest-risk contract**, not with the easiest file. - **Evidence over assertion.** "Sensitive-value scan: 6 pattern classes, 0 hits" beats "no secrets included". - **The checklist is a verification log, not decoration.** Checking a box without doing the check is a false statement to the reviewer. ## 3. Why this format helps deployment understanding The PR carries the deployment story end to end: what approval authorizes → what was verified → what the risks are → how to roll back. A user following great-pm's loop reads spec → build PR → review → merge → deploy and at every step knows exactly what has and has not happened. Nothing rides on memory or chat scroll. ## 4. Anti-patterns — ban these - **"Misc fixes" / "Update files" titles** — outcome-free titles force the reviewer to reverse-engineer intent. - **Summaries that assume the reviewer read the issue/chat** — the PR must stand alone. - **Unlabeled numbers** — implying measured results that are actually hopes. - **Empty or missing Risk / Rollback sections** — the two sections that matter most in an incident are the two most often skipped. - **Out-of-scope creep** — the Out-of-scope section exists so small "while I was here" changes don't ride along unreviewed. - **Checked boxes, unchecked work** — see Rule above. ## 5. Output shape A PR the reviewer can approve without opening the diff, and an operator can roll back without asking anyone. If the reviewer asks "what does merging this actually do?", the PR failed.