| name | pr-description |
| metadata | {"version":"0.24.6"} |
| description | Write a high-context PR description for any substantial PR. Use whenever creating or editing a pull request body — the description must let a reader with zero prior context understand what is being built, why, where it sits in the larger system, and exactly what changed, without digging through tickets or code. |
High-quality PR descriptions
A PR description is a durable design record, useful long after the merge.
Write for a smart colleague who has never seen this part of the system.
Trivial PRs (typo, one-line fix) may use a short body; everything else
follows this structure.
Structure
1. Title
Clear, specific, ticket-linked: #98: ia-render — reader plane write path.
2. The big picture (what we're building, where this PR fits)
Product context in plain language: the platform, the epic/capability this
belongs to, the epic broken into a numbered pipeline with this PR marked:
Step 1: ...
Step 2: ...
Step 3: ... <== THIS PR
Step 4: ...
Define domain terms on first use (fold, ledger, sidecar, MCP, ...).
3. Who actually calls this? / runtime context
The real caller and execution model: human + AI assistant, background job,
hook, webhook, UI? What surrounding system runs it? Does anything run
automatically or is confirmation gated? Security/permission notes (e.g.
"forwards the user's real token").
4. The problem this PR solves
Concrete, numbered pain points that exist today. Why the naive approach
fails and what correct behavior must be. The reader should feel the pain
the PR eliminates.
5. What this PR actually does (scope)
The ticket's exact ask, then confirmation the PR delivers precisely that.
Explicit in-scope / out-of-scope boundaries.
6. What exactly was added / changed
File by file (or component by component): path, what it contains, why it
was designed that way (especially non-obvious decisions), implementation
constraints (framework-free, no schema drift, deterministic output, ...).
Describe new tools/prompts/schemas clearly.
7. The sequence / flow the code enforces
For multi-step processes (especially ones an AI must follow): exact ordered
steps, decision points, confirmation gates, error handling, and explicit
"never do X" rules.
8. How it was tested
Honest and specific: unit tests (count + coverage), how they were run,
smoke tests, what was NOT tested and why (and when it will be), CI status.
9. Deliberately out of scope
What a reader might expect but is intentionally left for later tickets.
Prevents scope-creep comments; shows intentional design.
10. Ticket glossary (recommended)
Every ticket mentioned, one line each, current status:
| Ticket | What it is | Status |
|--------|----------------------------------------|-------------|
| #91 | Epic: IA & content model | In progress |
| #98 | This PR | In progress |
Style rules
- Plain language over jargon; define terms on first use.
- Short paragraphs, numbered/bulleted lists.
- Make the "why" as clear as the "what".
- Be precise about what this PR does NOT do.
- Professional, direct, slightly pedagogical tone.
- Call out non-obvious backend behaviors and traps explicitly so future
agents and humans don't rediscover them the hard way.
- Keep the repo's standard PR footer (generated-with attribution) intact.
Checklist before submitting
