Generate a PR description from the linked IntentSpec

PR descriptions are usually written last, in a hurry, and contain less context than the commit messages. The reviewer sees "fix login bug" and a 200-line diff and has to reconstruct intent from the code alone. This use case fixes the handoff at the last mile: the PR description carries forward the spec's goal, outcomes, and verification criteria.

The input

Two things:

• A linked IntentSpec — the spec the work was built against, in Pathmode
• A branch diff — usually pulled from git log or the PR's pre-existing summary

The link can be a slug in the branch name (intent-abc123-add-password-reset) or a manual lookup at PR-creation time.

The flow

1. Use the export flow on the spec. Each IntentSpec has an Export → PR description option. It pulls:

• The objective (one sentence)
• The outcomes that should be true after merge
• The verification criteria (manual + automated)
• The edge cases the work needed to handle
• Any out-of-scope notes

2. Paste into the PR template. Pathmode formats it as markdown with the right section headers your team uses. If you have a PR template, the export honors it.

3. Add the diff context. A short section: what changed, what didn't, where the surprises were. The spec gives the what; this section gives the how.

4. Link back. The export includes a permalink to the spec. Reviewers can drill in if they need the full evidence chain.

The output

A PR description that lets a reviewer answer in 60 seconds:

• What is this for? — from the spec's objective
• How will I know it works? — from the verification criteria
• What edge cases were considered? — from the spec's edge case list
• What's explicitly out of scope? — so they don't ask about it

Reviewers go from "I'll get to this when I have an hour" to "I can review this now." Cycle time drops, and the spec stays in lockstep with the code.

Why this beats writing PR descriptions from scratch

Most PR descriptions are a thin re-derivation of the spec, written by the implementer who already lost two hours coding. They're inconsistent in quality. They drift from what was actually agreed. And they bury the verification plan, which is the part the reviewer needs most.

When the PR description is exported from the spec, it's automatically consistent with the spec — and the spec was already reviewed.

Try it yourself

1. Open a finished IntentSpec
2. Click Export → PR description
3. Paste into your PR
4. Add a 3-line "what changed" note above the auto-generated section

Related

• Use case: Hand off a spec to Claude Code without losing context
• Playbook: The Anatomy of an Agent-Ready Spec
• Use case: Audit a draft spec for missing edge cases