Make PR

/flow-next:make-pr takes a spec with done tasks and a branch ahead of main and produces a PR body designed for the reviewer’s attention, not for the author’s checklist.

Creates the PR directly — no confirm gate

Invoking the skill is the intent, so make-pr pushes and opens the PR directly — there is no “create / abort” confirm prompt. The body is deterministic (every field traces to flowctl spec export-cognitive-aid), and the default is a reversible draft chosen by a smart draft/ready heuristic — open items make it a draft. The only prompts are Phase 0 info prompts to resolve something it cannot derive (no --base and no detection match, or no spec detected) — never “do you want to create it?”. The escape hatch is --dry-run (print the body without creating), and --ready / --draft force the draft state.

What lands in the body

The change, top to bottom — one versioned, intent-ordered walkthrough: grounded thesis and proof, logical implementation groups, exact file membership, deliberate non-changes, and verification.
TL;DR of the change in two or three sentences.
R-ID coverage table: each criterion → task → evidence commits.
Critical changes: the ≤7 highest-risk highlights.
How to review this PR — trust calibration: what the pipeline already verified mechanically (tests, gates, cross-model review, R-ID coverage — stated honestly, never overclaimed) and therefore what the human’s job actually is.
Review plan — every changed area risk-bucketed into Must review (with why it’s risky, one concrete what-to-check question, and the symbol to open) / Spot-check / Safe to skim (with the derivation named — generated mirrors and byte-identical copies never count as review risk), under a hard ≤~30% must-review focus budget. The reviewer reads the ~20-30% that carries judgment risk and skips the rest with confidence.
Decisions captured during work.
Memory entries left behind in .flow/memory/.
Glossary and strategy notes when terminology shifted.
Open items and explicit deferrals.
Mermaid diagrams when the change is structural.

Why a cognitive-aid body

A reviewer should be able to decide where to focus before skimming a single diff line — and, just as important, know which parts are safe to skip and why. The review-surfacing contract is eval-tuned: blind-judged on a real shipped PR, the old reviewer-focus list scored 7/10 on reviewer-effort and 5/10 on trust calibration; the shipped How-to-review + Review-plan sections score 9/9 (with actionability and honesty held at 9/8+). The body also surfaces uncovered R-IDs with a ⚠️ flag, so anything the spec promised but the diff did not deliver is visible at the top of the page.

Every claim references real files and SHAs only. There is no template filler.

One portable walkthrough, three render surfaces

Make PR persists the walkthrough as an immutable v1 JSON generation under .flow/artifacts/<spec-id>/pr-cognitive-aid/<artifactId>.json. Its artifact ID and base/head SHAs decide currentness; stale or invalid generations remain evidence but cannot supply current verification or ship claims.

The same validated object drives the structured artifact, GitHub Markdown, and the optional HTML lens. Consumers preserve source bindings, group order and kinds, exact file membership, separate Git changeType and review attentionClass, file-level R-ID/task links, deliberate non-changes, and verification. HTML may add navigation and bounded inline diffs; it cannot reclassify files or blend stale and legacy data. The lens embeds flowctl’s lossless HTML-safe JSON carrier, so consumers can recover the exact v1 object. It stays local-only and leaves the reviewed head unchanged; committing the lens would advance that head and stale its own input.

For downstream integrations, Flow-Next ships a maximum-normal v1 fixture with metadata pinning its source path, source commit, and exact SHA-256. Consumers such as Flow Swarm vendor byte-identical fixture and metadata copies, validate the local digest, and run without cross-repository network access in CI. The metadata also pins a strict <100 ms p95 validation-plus-Markdown-render budget over 30 warm runs. This supersedes the original 50 ms target after a representative parallel-suite observation of 90.57 ms—operationally negligible within the full workflow.

Spec-driven, not template-driven

Every field in the body traces back to a field in:

flowctl spec export-cognitive-aid <spec-id>

When attribution is unknown, the body says so honestly — unclear or uncovered — instead of inventing a reasonable-sounding sentence.

Flags

Flag	Effect
`--draft` / `--ready`	Force draft or ready state.
`--no-mermaid`	Skip diagram generation.
`--memory`	Write a `knowledge/architecture-patterns/` memory entry alongside the PR.
`--dry-run`	Print the body to stdout without pushing or opening a PR.
`--base <ref>`	Override base-branch detection.

App/bot-authored PRs — `FLOW_PR_CREATE_CMD`

By default make-pr opens the PR with gh pr create, so the PR is authored by whatever identity gh is logged in as. Repos that require App- or bot-authored PRs — the canonical case is a single-maintainer repo with required_approving_review_count: 1, where GitHub forbids approving your own PR, making a human-authored PR unmergeable — can interpose the create call:

export FLOW_PR_CREATE_CMD=/path/to/wrapper

The wrapper receives make-pr’s stable argument contract — --title <t> --body-file <f> [--draft] --base <branch> --head <branch> — and must exit 0 and print the PR URL on success. Extra logging is tolerated: make-pr extracts the last …/pull/<n> from the combined output rather than trusting it verbatim. The expansion is whitespace-split and never eval’d, so the wrapper path must not contain spaces. On failure the wrapper’s combined output is surfaced verbatim, and wrappers that proxy gh inherit make-pr’s eventual-consistency retry for free.

Scope is the create call only — authorship is fixed at creation. gh remains a preflight requirement (gh pr view / gh pr edit, --update mode, and the post-create link repair all use it), and identity work — minting App installation tokens — belongs to the wrapper, not flow-next. Wrapper-free alternative for short runs: export GH_TOKEN with an App installation token; gh prefers it over stored auth. Installation tokens expire after an hour, which is exactly when the wrapper seam earns its keep.

Tracker linkage and Linear Diffs

When the tracker bridge is active and the spec is linked, make-pr unconditionally links the new PR to its tracker issue — no separate opt-in. For Linear that means a non-closing Ref WOR-N in the body (plus a rich attachment on the GraphQL transport), which makes the PR render as a Linear Diff inside the issue; for GitHub it is a native Refs #N cross-link. Non-closing is deliberate so merge never auto-completes the issue — spec-completion-review owns Done.

Ralph-friendly

Not Ralph-blocked. Under Ralph the Phase 0 prompts are skipped and --draft is forced; the PR is still created directly and its URL emitted to stdout so the autonomous loop can move on while a human reviews.

What gets forbidden

No quoting raw diff content. The diff is the diff; the body is the map to it.
No gh pr merge from the skill. Merge is a human decision.
No inflating scope beyond what the diff supports. If the spec covered more than the diff did, the uncovered criteria appear as gaps, not as accomplishments.

Worked example

/flow-next:make-pr fn-12-export-json-flag

Rendering PR body from flow state: spec + 2 task done-summaries + evidence commits...
R-ID coverage: R1 (a1b2c3d), R2 (a1b2c3d), R3 (e4f5a6b) - 3/3 covered
Review plan: Must review src/export/json.ts; Spot-check tests; Safe to skim docs
Opened: https://github.com/acme/api/pull/214 (draft)

The body is generated from state the pipeline already verified - the reviewer gets an R-ID coverage table, not prose.

Dynamic usage

Recipes that compose with make-pr in the cookbook:

Evidence-first - the R-ID coverage table is the spec’s acceptance criteria proving themselves in the PR.
One-shot chains - “work the spec and open the PR when review ships” ends here without a second prompt.
Team patterns - the PR-as-cognitive-aid is handover object #6; your reviewer starts from the trust frame, not from zero.

Next step

/flow-next:resolve-pr