Pull requests are a public, reader-facing surface in the flotilla tree — the same
reader-modeling standard as operator comms applies here. A reviewer opens your PR cold
from main: no issue-thread memory, no coordination chat, no shared vocabulary from
your desk session. The title and description must answer what changed and why it
matters in plain language a capable engineer can follow without decoding internal
shorthand.
This doc is the canonical home for PR title/description rules. Agents load the
companion skill .claude/skills/flotilla-pr-authoring/SKILL.md
for the mechanical workflow (file-based delivery, gh invocation, Mermaid checks).
Principle: OPERATING-PRINCIPLES.md §5 (reader-modeling).
When a PR, ship note, parade link, or dashboard card will be shown to the operator,
the engineering description is not the opening. Complete the ## Operator summary
template in this order:
- Before — what the operator or product user could not do, see, or trust.
- Change — the behavior that changed, with fleet terms glossed on first use.
- After — what is now possible or trustworthy.
- Identifiers — issue, PR, exact head, and merge SHA in the footer only.
Validate it before publishing:
flotilla pr body lint --audience operator /path/to/pr-body.mdEngineering detail remains below the operator summary and may retain its technical
register. The lint shares its audience lexicon with flotilla parade lint, so the
two operator surfaces cannot drift into separate definitions of readable prose.
Large diffs: escalate to the comprehensive-pr-description skill (installed in the
agent's skill path) for the full chunk/Mermaid/template treatment.
Review gate: coordinators follow coordinator-runbooks/merge-gate.md.
Model one person: a technically capable reviewer who has not been in your session. They need to:
- Understand the purpose of the change in the first screenful.
- Follow logically distinct units of work — not a commit log, not a file inventory.
- See why each unit exists (problem → approach), with jargon glossed on first use.
- Trust the verification section because it cites checkable facts, not vibes.
If the description reads like it was written for a linter, a merge bot, or another
agent's context window, rewrite it. Gate vocabulary (CLEAR, cubic, P1,
flotilla-dispatch-*) belongs in coordination traffic or a detail footer — not in
the lead paragraph.
The title is the one-line answer to "what does this PR introduce?"
| Avoid | Prefer |
|---|---|
fix stuff / updates / WIP |
Keep routine turn-finals in the dash ledger |
feat/org-truth-pr4 (branch name as title) |
Expose org DAG on dash topology API and goals spokes |
Address review feedback |
Reject cyclic fleet-org.yaml at load time with path in error |
| Internal codenames without gloss | Generic capability names from flotilla.example.json roles |
Shape: imperative or outcome phrase; ≤ ~72 characters when practical; no trailing
period. Name the behavior or capability, not the process (Phase 2, PR4,
gate fixes).
A tight description is enough:
## Summary
<2–4 sentences: what changed mechanically and why.>
## Test plan
- [x] <what you ran>Use the logical-chunk shape (full template in comprehensive-pr-description):
- TL;DR — one paragraph with the headline outcome.
- Why this PR exists — problem, timing, approach; cite issues/PRs with one-line glosses.
- Logical chunks — each with What / Why; 6–12 chunks for large diffs.
- Verification — table of surfaces and states (test counts, CI, review tools).
- Test plan — checklist; unchecked items explain deferral.
- References — issues, sibling PRs, design docs, each glossed.
Organize by what changed, not by commit SHA or file path. Phases and branch names are authoring metadata, not reader structure.
Diagrams replace paragraphs when they show structure or flow the reader would otherwise have to reconstruct. Skip them for two-step flows prose handles fine.
| Showing | Mermaid type |
|---|---|
| Decision / refactor flow | flowchart (LR or TB) |
| Process interactions | sequenceDiagram |
| State machine | stateDiagram-v2 |
| Schema / FK relationships | erDiagram |
| Package or module hierarchy | flowchart TB with subgraph |
GitHub renders Mermaid only inside fenced code blocks tagged mermaid. Common
failures:
- Missing blank lines — put an empty line before and after the fence so the block is not glued to a heading or list item.
- Indented fences — top-level fences start at column 0 in the markdown file.
- Special characters in labels — wrap node text in double quotes when it
contains
(),[], or:. - Subgraph syntax — use
subgraph id [Label]; test render before pushing.
Example — in the PR body file, separate the heading, prose, diagram, and closing
prose with blank lines. The mermaid fence is top-level (column 0), not nested
inside a list item:
## Data path
The watch daemon and dash share one org DAG source.
```mermaid
flowchart LR
Channels["channels[] in roster"] --> Derive["DeriveFromChannels"]
OrgFile["fleet-org.yaml"] --> Agree["Agree + validate"]
Derive --> Config["Config.Org()"]
Agree --> Config
Config --> Watch["watch synthesis"]
Config --> Dash["/api/topology"]
```
Both consumers read the same derived graph.
After pushing the body, open the PR in the browser and confirm diagrams render. Syntax errors show as plain text and are easy to miss in the terminal.
PR bodies are multi-line markdown with backticks, quotes, $, and Mermaid
braces. Passing them through Bash string interpolation (-b "$(cat <<'EOF'…)",
echo, printf, heredocs inside $(…)) corrupts content silently or turns
Mermaid into shell syntax errors.
Rule: compose the description in a file (editor or Write tool), then
submit that file bytes verbatim.
mkdir -p .claude/pr-bodies
# compose at .claude/pr-bodies/pr-<N-or-branch>.md — never inline in gh -b
gh pr create \
--title="Expose org DAG on dash topology API" \
--body-file=.claude/pr-bodies/pr-my-feature.mdmkdir -p .claude/pr-bodies
gh pr view <N> --json body --jq '.body' > .claude/pr-bodies/pr-<N>.md
# edit the file on disk (additive updates preferred — see comprehensive-pr-description)
gh pr edit <N> --body-file=.claude/pr-bodies/pr-<N>.md
# verify the edit took:
gh pr view <N> --json body --jq '.body' | head -5If gh pr edit fails on classic project cards, use the REST API (body as raw JSON
string — preserves newlines):
jq -Rs '{body: .}' < .claude/pr-bodies/pr-<N>.md > /tmp/pr-body.json
gh api -X PATCH repos/<owner>/<repo>/pulls/<N> --input /tmp/pr-body.jsonUse jq -Rs (raw + slurp), not --field body=@file, which chokes on markdown
quotes.
internal/dash/tracker/gh.go already submits issue bodies via stdin
(gh issue create --body-file=-) so shell parsing cannot reinterpret content.
PR authoring follows the same discipline.
gh pr create -b "$(python -c 'print("""...""")")"— quote/escape roulette.- Heredoc inside command substitution for the final body.
- Piping through
sed/awkto "fix" Mermaid after composition — edit the source file. - Composing from memory on
gh pr editwhen a description already exists — fetch to disk first, then add.
Direct GitHub API calls (gh api, PATCH pulls) are fine when the body file is
the payload source.
PR text is public. Use generic roles and examples from flotilla.example.json
(xo, backend, frontend, …). Never put deployment roster paths, real operator
handles, guild ids, or fleet-specific desk names in titles or bodies. Redact to the
generic capability; see private-public-boundary.md.
Screenshots and recordings are public artifacts too — and the text-based
boundary guard cannot see inside them. A capture of a UI serving a real
deployment's state publishes desk names, goal titles, and descriptions as
pixels. Any image committed to the repo or embedded in a PR must be generated
from the committed example fixture state (flotilla.example.json + the
example goals/org files) — never from a live deployment. If fixture-state
capture is impractical, commit no media and state in the PR body where the walk
evidence is staged privately; the reviewer verifies independently. Remember
that a squash merge does not sanitize history: every commit pushed to a PR
branch remains publicly reachable via the frozen pull ref, so a leaked image
must never be pushed in the first place.
- Title — states the capability/outcome, not the branch or gate phase.
- Lead — a stranger learns what changed without opening the diff.
- Chunks — logical units with What/Why, not commit/file lists.
- Diagrams — each earns its space; blank lines around fences; verified in browser.
- Delivery — body read from
.claude/pr-bodies/*.mdvia--body-fileor REST. - Verification — specific counts and surfaces, not "tests pass."
- Boundary — no deployment-specific identifiers; any committed/embedded media rendered from example fixture state only.