The early versions of Pylon produced PR descriptions that said things like "Refactor: update imports in auth module." That is correct, technically, and completely useless to a reviewer. It tells you what happened in terms that are already visible in the diff title. It does not tell you why it happened, what the risk surface is, or where to focus your review attention.
We spent several iterations on the description format because we noticed a pattern in the early-access feedback: teams that had mixed feelings about Pylon-generated PRs often cited the descriptions as part of the reason. Not the code quality; the description quality. An engineer who opens a PR and cannot quickly understand the intent and scope will approach the review skeptically, will read more of the diff than necessary, and will spend more time on review overall. That skepticism is reasonable and earned when the description is thin.
The six-section structure
The PR description format we settled on has six sections. Not all sections appear in every PR; some are conditional based on what the job type and scope require. But the structure is consistent enough that reviewers who see multiple Pylon PRs quickly learn where to find what they are looking for.
Summary: two to four sentences stating what this PR does and why. The "why" is derived from the ticket context if a ticket is linked, or from the job parameters if no ticket is linked. "This PR upgrades the stripe dependency from 12.3.1 to 12.9.0 to resolve GHSA-2024-4421, which allows an attacker to bypass signature verification on webhook payloads. No API changes are required; the fix is backward-compatible with all current integration points." That is a useful summary. It gives the reviewer immediate context without requiring them to look up the CVE separately.
Files changed: a structured list of which files were modified and why each was touched. This section is not the same as the GitHub diff file list; it includes the reason for each file's inclusion. "payment-service/package.json: dependency upgrade. payment-service/src/webhook.js: updated signature verification call to use new SDK method. payment-service/tests/webhook.test.js: updated mock to match new SDK response shape." A reviewer can use this to decide which files to prioritize in the diff.
Tests: what test changes were made and why. New tests added are listed with the behavior they cover. Modified tests are listed with what changed in the assertion and why. This section is present for every Pylon PR because every job runs the test suite, and if tests were modified, the reviewer needs to understand the modification intent.
Reviewer focus: the single most important section. Two to three sentences telling the reviewer exactly what to look at carefully. "The webhook signature verification path changed in lines 47-63 of webhook.js. The previous implementation accepted both HMAC-SHA256 and HMAC-SHA512 signatures; the new SDK only supports SHA256. Verify that no integrations in this environment send SHA512 signatures." A reviewer who reads only this section and the summary can make an intelligent decision about whether to approve or request changes. The diff review becomes targeted confirmation rather than open-ended investigation.
What was not changed (when relevant): sometimes the most useful information in a PR is what was explicitly left alone and why. "The retry logic in webhook-processor.js was reviewed but not modified. The current retry behavior is safe with the new SDK version; modifying it would require a separate PR with dedicated testing." This section prevents the review from turning into "why didn't you also fix X" questions that slow down approval.
Linked ticket status (when applicable): if the PR is linked to a Jira or Linear ticket, the last line of the description states the ticket ID and its current status. "PYMT-2204: marked In Review. Will mark Done automatically on merge." Short, factual, prevents the PR from being approved and then sitting until someone remembers to update the tracker.
Calibrating the reviewer focus section
The "reviewer focus" section is the hardest part of the description to get right, because it requires the agent to reason about risk, not just describe what happened.
Risk identification in the context graph comes from a few signals: how frequently the changed files have been modified recently (high change frequency suggests active development where an error might collide with ongoing work); how many other modules import the changed files (high fan-in means a change here has more potential blast radius); whether the changed code is in a test-covered path or not; and whether the change touches any functions flagged as security-sensitive in the codebase conventions.
We do not have a formal risk scoring system that outputs a number. That kind of precision would be false confidence. Instead, the agent identifies the two or three factors that most elevate this PR above the baseline and surfaces them directly in the reviewer focus section. When no clear risk factors are present, the reviewer focus section says so: "This is a low-risk change. The modified code has 100 percent branch coverage and no other modules import the changed files directly."
What happens when the description is wrong
We have had cases where the PR description stated something incorrect about the change scope, usually because the context graph had a stale or inaccurate edge and the agent's scope analysis was off. When a reviewer catches this and comments on it, Pylon reads the review thread and updates the description in the next revision. The correction is acknowledged explicitly: "Updated: corrected the reviewer focus section per review comment from @reviewer. The webhook-processor retry logic was also affected by this change; the original description missed this dependency."
Transparency about corrections is important. A description that was wrong and is now right without acknowledgment makes it harder for the reviewer to trust future Pylon PRs. A description that explicitly notes what was corrected and why is part of building the kind of accountable track record that earns trust over time.
The description is not decorative. It is functional documentation of why the code is the way it is, written at the moment when that reasoning is most accessible. For teams that rely on git history and PR context for future debugging, the description Pylon writes is often more detailed than what a human engineer would write under time pressure. That is one of the practical benefits of having an agent do the writeup: the agent does not have another three tickets waiting while it writes the description.