flow-next-make-pr

/flow-next:make-pr — PR-as-cognitive-aid

A reviewable PR body is itself an artefact: it lets a human decide where to focus before skimming the diff. flow-next already collects every input that body needs — the spec with R-IDs, per-task done summaries and evidence commits, decisions / bug / architecture-patterns memory entries, glossary changes, strategy alignment, deferred review findings, the git diff itself. This skill stitches those into a structured body, optionally adds mermaid diagrams for module-boundary changes, and pushes via gh pr create.

The host agent (Claude Code / Codex / Droid) reads the structured payload from flowctl spec export-cognitive-aid and synthesizes the body directly. Every claim in the body must trace to a structured field in the export payload — never fabricate file paths, SHAs, R-ID attributions, or "why" reasoning. Unknown attribution is honest ("uncovered" / "unclear") rather than invented. The host is competent at "what looks important here?" given the rich input; no second-model review pass is needed (the structured payload does the heavy lifting).

flowctl provides only thin plumbing: flowctl spec export-cognitive-aid <spec-id> --base <ref> --json aggregates the inputs into a single JSON payload (Task 1 of this spec). The skill renders the body, then pushes and creates the PR directly — no confirm prompt (invoking make-pr is the intent; the body is deterministic; the default is a reversible draft). --dry-run prints the body without creating; --ready/--draft set draft state.

Read [workflow.md](workflow.md) for the full phase-by-phase execution. Read [phases.md](phases.md) for the per-phase Done-when checklists. Read [mermaid-rules.md](mermaid-rules.md) before emitting any mermaid codefence — it defines reserved words, escape patterns, shape selection, and the pre-emission validation checklist.

Preamble

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks (here and in workflow.md / phases.md) use $FLOWCTL:

FLOWCTL="$HOME/.codex/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Inline skill (no context: fork) — plain-text numbered prompt must stay reachable for the Phase 0 info prompts (resolve a missing base ref / undetected spec id — never a confirm gate). Subagents can't call plain-text numbered prompts (Claude Code issues #12890, #34592). There is no Phase 4 confirm prompt — make-pr creates the PR directly.

Mode Detection

Parse $ARGUMENTS as a flag list. Recognized flags: --draft, --ready, --no-mermaid, --memory, --dry-run, --base <ref> (consumes the next token), and the literal token mode:autonomous. Strip recognized tokens; the remainder (if any) is the optional spec id.

RAW_ARGS="$ARGUMENTS"
DRAFT_FORCE="auto" # auto | draft | ready
NO_MERMAID=0
WRITE_MEMORY=0
DRY_RUN=0
BASE_REF=""
SPEC_ID=""
AUTONOMOUS=0

# Tokenize and walk the argument list. The loop handles both `--base=<ref>`
# and space-separated `--base <ref>` via a PREV token holder. Deliberately NO
# bash positional parameters here — the host's argument interpolation rewrites
# positional tokens inside skill code blocks (pilot dogfood finding, 1.13.0).
PREV=""
for ARG in $RAW_ARGS; do
 case "$PREV" in
 --base) BASE_REF="$ARG"; PREV=""; continue ;;
 esac
 case "$ARG" in
 --draft) DRAFT_FORCE="draft" ;;
 --ready) DRAFT_FORCE="ready" ;;
 --no-mermaid) NO_MERMAID=1 ;;
 --memory) WRITE_MEMORY=1 ;;
 --dry-run) DRY_RUN=1 ;;
 --base) PREV="$ARG" ;;
 --base=*) BASE_REF="${ARG#--base=}" ;;
 mode:autonomous) AUTONOMOUS=1 ;;
 -*) echo "Unknown flag: $ARG" >&2; exit 2 ;;
 *) SPEC_ID="$ARG" ;;
 esac
done
[[ -n "$PREV" ]] && { echo "Flag $PREV given without a value" >&2; exit 2; }

# Secondary signal: process-level autonomous driver (env survives only
# within one process tree; the token is the primary, prose-safe carrier).
if [[ "${FLOW_AUTONOMOUS:-}" == "1" ]]; then
 AUTONOMOUS=1
fi

| Flag | Effect | |------|--------| | --draft | Force draft PR regardless of open-items count or Ralph context. | | --ready | Force non-draft PR. Conflicts with --draft (last flag wins; surface the conflict). | | --no-mermaid | Skip Phase 3 entirely. Mermaid prose summaries are also skipped. | | --memory | After PR creation, write a knowledge/architecture-patterns/ memory entry summarizing what shipped. Idempotent — rerun adds no second entry for the same spec id. | | --dry-run | Skip Phase 4 entirely. Render body to stdout. Useful for inspection or … --dry-run \| pbcopy. | | --base <ref> | Override base-branch detection cascade. Useful when the team's default branch is develop, etc. | | mode:autonomous | Autonomous mode: Phase 0 info prompts hard-error instead of asking; draft forced. Sets AUTONOMOUS=1 only — NEVER RALPH. Also derived from FLOW_AUTONOMOUS=1. |

Ralph mode (FLOW_RALPH=1 or REVIEW_RECEIPT_PATH set) is detected separately in workflow.md §0.0 — the skill is not Ralph-blocked. Under Ralph the skill hard-errors instead of asking the Phase 0 info prompts, forces --draft, and emits the PR URL to stdout. (The PR is created directly in both modes — the only difference is forced-draft + no Phase 0 prompts under Ralph.) Autonomous mode is a SEPARATE flag: AUTONOMOUS=1 derives only from the mode:autonomous token or FLOW_AUTONOMOUS=1 and never sets RALPH. Under RALPH || AUTONOMOUS the Phase 0 info prompts hard-error and --draft is forced (--ready ignored with a note); the PR_URL= stdout contract and all receipt/harness semantics remain Ralph-only.

Interaction Principles

Ask the user via plain text. Render the options below as a numbered list 1. … N., followed by a final option N+1. Other — type your own answer. Print the question, then the numbered list, then stop and wait for the user's next message before continuing. Parse the reply as: a bare number 1–N+1 → that option; the literal text of an option label → that option; free text after Other → custom answer.

• Ask one question at a time via plain-text numbered prompt. Never silently skip the question.
• Lead with the recommended option and a one-sentence rationale.
• No confirm gate. make-pr opens the PR without asking. Phase 0 asks only to resolve info it cannot derive (no --base and no detection match; no spec detected) — never "do you want to create it?". Not-all-tasks-done warns and proceeds (the open items make it a draft). Skip questions when context resolves cleanly.
• Ralph and autonomous modes skip all questions. Detect both once at Phase 0 and route deterministically; a genuinely unanswerable gap hard-errors with a clear message (NEEDS_HUMAN-style) instead of hanging on a prompt.

Hallucination guardrails

The body is synthesized from the export payload. Every claim must trace to a structured field. The skill explicitly forbids:

• Inventing file paths. Only paths returned by git diff --name-status (via the diff.files array) appear in Critical Changes / Where to look. No "I think there's also a config file" content.
• Fabricating commit SHAs. SHAs come from tasks[].evidence[].commits and git log --oneline base..HEAD only.
• Guessing R-ID coverage. Coverage is computed from task satisfies frontmatter and commit-message R-ID references. Uncovered R-IDs get a ⚠️ flag, never a confident attribution.
• Inventing "why" reasoning. Decision context comes from memory.decisions[] entries' bodies. If no decision entry exists for a change, the body says so explicitly rather than narrating a plausible-sounding rationale.
• Quoting raw diff content. The body talks ABOUT the diff (paths, churn, modules). Never includes code snippets — privacy + secret-leakage risk; GitHub renders the actual diff below the body.
• Synthesizing review findings. Findings come from reviews.deferred[] and `reviews.suppres