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 agent that did the work writes the PR description from the spec it was building against, so the goal, outcomes, and verification criteria carry forward instead of evaporating.

The input

Two things, both already in the agent's context by the time the work is done:

• The IntentSpec the work was built against, pulled live over the Pathmode MCP server or pasted in from the export
• The diff itself, which the agent wrote

Nothing to gather. The moment before "open a PR" is the moment everything needed for a good description is already in one place.

The flow

1. The agent re-reads the spec. Over the MCP connection it calls get_intent (or get_agent_prompt for the fully formatted version) and gets the objective, the outcomes that should be true after merge, the verification checks, the edge cases, and the out-of-scope notes as structured data. If you handed off by copy-paste, the exported prompt already contains all of it.

2. Ask for the PR description from the spec, not the diff. One instruction: "Write the PR description from the intent you built against." The spec gives the what and why; the agent adds a short how section from the diff: what changed, what didn't, where the surprises were.

3. Have it flag any drift. The useful twist: ask the agent to note where the implementation diverged from the spec. If it recorded findings mid-build with record_implementation_finding, those belong in the description too, because they're exactly what a reviewer needs to weigh in on.

4. Link back. Include the intent's URL so reviewers can drill into the full evidence chain, and so the verification run that grades this PR later lands on the same record.

The output

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

• What is this for? From the spec's objective, not a re-derivation of it
• How will I know it works? From the verification checks the spec already carries
• What edge cases were considered? Enumerated, from the spec's edge case list
• What's explicitly out of scope? So they don't ask about it
• Where did the build disagree with the spec? From the agent's own findings

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 description is written from the spec, it's automatically consistent with the spec, and the spec was already reviewed. The agent doing it costs nothing: it's one more instruction at the end of a run where the spec and the diff are both already in context.

Try it yourself

1. Hand off a spec to your agent (MCP pull or export, either works)
2. When the work is done, ask: "Write the PR description from the intent you built against, and flag anywhere the implementation diverged."
3. Add the intent link, open the PR
4. Run verification against the same PR to close the loop

Related

• Use case: Verify the pull request against the spec it was built from
• Use case: Hand off a spec to Claude Code without losing context
• Playbook: The Anatomy of an Agent-Ready Spec