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 for reviewers and a supported intent reference, such as pathmode:<intent-id> in the PR body, for webhook matching. Confirm the PR is linked to the revision you built against.
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 can compare the intended behavior with the diff and the checks that actually ran. Report failed or unrun checks explicitly; a verification plan is not a test result.
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.
Using the agreed spec gives the draft a clear source for the what and why. Review the generated description against that revision and the actual test results before opening the PR; the agent can still omit or misstate a detail.
Try it yourself
- Hand off a spec to your agent (MCP pull or export, either works)
- When the work is done, ask: "Write the PR description from the intent you built against, and flag anywhere the implementation diverged."
- Add the intent link, open the PR
- Run verification against the same PR to close the loop
Related
Bring this workflow to your team.
Keep the evidence, decisions, and follow-up work together in your product.
Start with Pathmode