Forge PR Writing

Write PR descriptions that fellow devs actually want to read. The writing guidance below is forge-agnostic — only the gh commands in the "Updating existing PRs" section are GitHub-specific today. Bitbucket support is tracked in srid/agency#10.

Anti-patterns (what LLMs typically produce)

• Flat bullet lists of every file changed
• Implementation-detail dumps ("added foo parameter to bar function")
• Generic titles like "Update configuration" or "Fix bug in module"
• "## Changes" / "## Testing" / "## Summary" boilerplate headers
• Restating the diff in English
• Wall of prose for content that's actually a list, comparison, or flow — five features described in one sentence, two before/after fixes blended into a paragraph, an architecture seam explained in words instead of drawn

What to write instead

Title: Short, specific, interesting. Convey what changed from a user/dev perspective, not which files were touched. Use imperative mood. Under 70 chars.

Body: Open with a paragraph. Structure:

1. Opening paragraph — What this PR does and why, in 2-3 sentences. Bold the key behavioral change. If there's a motivating problem, state it directly.

2. Details — paragraph(s), bullet list, table, or fenced diagram, whichever fits the shape of the content (see Use structure when content is structured below). Only include if the approach is non-obvious, has trade-offs worth calling out, or has discrete moving parts that benefit from being shown rather than described. Use italics for subtle points; keep it high-level.

3. Anything notable — Breaking changes, migration steps, or things reviewers should pay attention to. Only if applicable. Use > blockquote for callouts.

Use structure when content is structured

Narrative is the right tool for the opening "what changed and why" paragraph and for asides — but the moment you find yourself writing "three loaders", "two refinements landed", or "the data passes through X then Y then Z", that's structure asking to be made visible. A comma-separated list of five features in prose is harder to scan than five bullets; a table beats a paragraph that says "previously Foo did X, now it does Y, and Bar previously did Z, now it does W."

Reach for these when they earn their keep:

• Bullet lists — discrete features, keyboard shortcuts, refinements, anything that isn't a narrative
• Tables — before/after fixes, per-variant comparisons (e.g. loader → format → vendor), trade-off matrices
• Fenced ASCII or mermaid diagrams — data flow, architecture seams, anything with shape that's easier to draw than describe
• ### subheaders — break long bodies into navigable sections (still avoid generic ## Summary / ## Changes)

The rule is use structure when content is structured, not always add structure. A small PR with one paragraph of motivation is fine; don't reach for a table just to look thorough.

Style rules

• Write for a dev skimming their PR feed — they should get the gist in 5 seconds
• Bold the most important phrase in each paragraph
• Italics for nuance, caveats, secondary points
• Bullet lists, tables, and fenced diagrams are encouraged when the content is genuinely structured (see Use structure when content is structured). Don't list the diff file-by-file or restate prose as a bulleted dump.
• ### subheaders are fine to break up long bodies; skip generic ## Summary / ## Changes headers
• No filler: "This PR...", "In this change...", "As part of..." — start with the substance
• Link to issues/discussions where relevant (Closes #123, See #456)
• If the PR is trivial (typo fix, version bump), a one-liner body is fine

Attribution footer

End every PR body with a one-line italic footer naming:

• the invoking workflow (the slash-command that drove this PR — e.g. /do), linked to its source repo (https://github.com/srid/agency),
• the agent (the harness identity — e.g. Claude Code, Codex, opencode), and
• the model (the specific model id you are running on — e.g. claude-opus-4-7, gpt-5-codex).

Reviewers should be able to tell at a glance what produced the diff:

Generated by /do on Claude Code (model claude-opus-4-7).

Use the values that are actually executing this run — do not guess or fabricate. If you genuinely cannot identify one of agent/model, write unknown rather than omitting the footer. If the PR is being written without an invoking workflow (forge-pr loaded directly, no /-command), drop the workflow phrase and lead with _Generated by Claude Code (model claude-opus-4-7)._. When updating an existing PR (see Updating existing PRs) and the current run's agent or model differs from what's already in the body, edit the existing footer in place rather than appending a second one.

Try it locally

If the repo is a GitHub Nix flake and the PR branch contains a buildable output (package, NixOS config, etc.), include a "Try it locally" section at the end of the body. Use the GitHub owner/repo and branch name to construct the command, and put it in a fenced sh code block (not inline backticks) so GitHub renders a copy button and the command doesn't line-wrap awkwardly:

### Try it locally

```sh
nix run github:<owner>/<repo>/<branch>
```

Adjust the command as needed — nix build for non-runnable outputs, add #<output> if the default package isn't the relevant one. Omit this section entirely if the change isn't meaningfully testable via nix run/build (e.g., CI-only changes, documentation, non-Nix repos, or non-GitHub forges where flake refs would be awkward).

Passing the body to gh safely

MANDATORY: Always pass --body to gh pr create / gh pr edit / gh pr comment via a single-quoted heredoc so backticks, $, and ! survive unescaped. Double-quoted --body "..." triggers shell command substitution on backticks, and escaping them with ``` produces literal backslashes in the rendered PR (breaking code fences — see juspay/kolu#402).

gh pr create --draft --title "..." --body "$(cat <<'EOF'
...body with ```sh fenced blocks``` intact...
EOF
)"

The 'EOF' (quoted delimiter) is load-bearing — it disables interpolation inside the heredoc. Never write backticks in the body as ```.

Updating existing PRs

When the user pushes further changes to an already-PR'd branch:

1. Check if the PR title/description still accurately reflects the full scope
2. If new commits meaningfully change what the PR does, update the title and/or body via the forge's edit command (gh pr edit on GitHub)
3. Don't rewrite from scratch — amend the existing description to cover new ground
4. Add a brief note about what changed if the scope expanded significantly

Examples

Bad (typical LLM output)

Title: Update NixOS configuration and add new service

## Summary
- Added `kolu` service configuration
- Updated `flake.lock`
- Modified port from 8080 to 8090
- Added health check endpoint
- Updated README

## Testing
- Tested locally

Good (small change — narrative is enough)

Title: Add kolu service with health monitoring

**Kolu now runs as a standalone NixOS service** with its own systemd
unit and a dedicated health-check endpoint. Previously it was bolted
onto the main app process, which made restarts disruptive.

The service binds to port 8090 to avoid clashing with the dev server.
*Health checks hit `/healthz` every 30s — systemd restarts the
service on three consecutive failures.*

Good (richer change — structure earns its keep)

When the change has a flow, several discrete features, and a couple of before/after refinements, show those instead of writing them out as prose:

Title: Export agent session as a self-contained HTML file

**Kolu can now export the active agent session as a portable,
self-contained HTML file** — Claude Code, OpenCode, or Codex, no
matter which one is running. The server reads the on-disk transcript,
normalizes it through a unified vendor-opaque IR, and ships back one
HTML document the browser opens in a new tab.

### How it fits together

```
Claude JSONL    ─┐
OpenCode SQLite ─┼─▶ loader ─▶ TranscriptEvent[] ─▶ renderer ─▶ HTML
Codex rollout   ─┘             (discriminated union)
```

The IR (`Transcript` in `anyagent/schemas`) is the key seam. The
renderer dispatches **only** on `event.kind` — never on `agentKind`.
_Adding a fourth integration is one new loader plus one `match` arm._

### What you get in the exported page

- **Header pills** — agent name, model, context-token count, PR link
- **Hide tools** — collapses tool-call cards for narrative reading
- **Theme** — cycles auto → light → dark
- **<kbd>j</kbd>/<kbd>k</kbd> nav** — jump between user prompts
- **Per-event icons** — person, robot, brain, wrench

### Refinements during review

| What was off | Fix |
| --- | --- |
| Claude loader threw `ENOENT` for new sessions; OpenCode/Codex returned `null` | All three loaders return `Transcript \| null` uniformly |
| OpenCode loader did per-message N+1 SQLite fetches | Collapsed into one ordered `LEFT JOIN` (~501 statements → 1) |

> _No streaming, by design — end-of-session export reads the whole
> transcript in one pass._

The flow diagram replaces a paragraph that would have to enumerate "Claude JSONL, OpenCode SQLite, Codex rollout — all converge on a single loader interface...". The bullet list replaces a comma-jammed sentence. The table replaces "Two refinements landed: first, the Claude loader used to throw...; second, the OpenCode loader collapsed...". Each structural element is doing work prose couldn't do as cleanly.