How we deal with slop at Corridor: PR Descriptions

Researchers from BetterUp Stanford Social Media Lab coined the term Workslop: “AI-generated content that looks good, but lacks substance.” In a survey of 1,150 US desk workers, they found that recipients of low-quality AI workslop reported spending about two additional hours dealing with each incident.

Corridor is a small, fast-moving, AI-native team, and fixing workslop can quickly consume the time AI saves us. Sloppy code takes time to fix, sloppy internal documents create confusion, and sloppy PR descriptions make changes harder to review. AI-native development requires intentionality: we need to spend some of the time AI saves us reducing that burden on our coworkers, future selves, and customers.

One recurring source of slop was pull request (PR) descriptions. An agent could explain a one-line fix under five different headings. To address this, we created a writing skill, a linter, and a PR description quality checker.

1. The problem with PR-description slop

Here's a one-line PR diff and the PR description that Claude Code wrote for it:

- FILES=$(git diff --name-only "$OLD_REV" "$NEW_REV" -- web/public/tools tool/VERSION)
+ FILES=$(git diff --name-only "$OLD_REV" "$NEW_REV" -- web/public/tools tool/VERSION ':(exclude)web/public/tools/*-init.sh')

-          FILES=$(git diff --name-only "$OLD_REV" "$NEW_REV" -- web/public/tools tool/VERSION)
+          FILES=$(git diff --name-only "$OLD_REV" "$NEW_REV" -- web/public/tools tool/VERSION ':(exclude)web/public/tools/*-init.sh')

FILES=$(git diff --name-only "$OLD_REV" "$NEW_REV" -- web/public/tools tool/VERSION ':(exclude)web/public/tools/*-init.sh')

Did a reviewer really need the same one-line change explained under “Before,” “After,” “What,” “How,” and “Motivation”? Probably not. We wanted our coding agents to write concise descriptions that any engineer could understand without having to wade through excessive repetition or confusing prose.

PR descriptions grew faster than code changes

We examined merged PRs from August 2025 through August 2026 to see how widespread this was. We measured description length in prose words: the explanatory text in paragraphs and bullet points, excluding headings, code blocks, tables, and block quotations.

We found that median PR description length increased by 983%, while median diff size increased by 55%.

Because larger changes could reasonably need longer explanations, we also compared descriptions within five diff-size groups. We again found that description length increased in every group. For 11–50-line diffs, for example, the median rose from 11 to 189 words, an increase of 1,618%.

The shift toward larger changes could not explain the growth on its own -- agents were writing more even for changes of a similar size.

Description length also differed by model

We also grouped PRs by the Claude model named in their merge commits. Opus 5 had the longest median description in this subset, about 7.6 times the median attributed to Opus 4.6.

The difference remained across PR diff size groups. Among PRs with 51–200-line changes, median description length ranged from 77 words for Opus 4.6 to 660.5 for Opus 5.

We realized that a writing standard needs to work across models, including ones that produce much longer explanations.

More words did not necessarily give reviewers more information

One description contained 1,302 prose words. It answered 13 review concerns, then repeated all 13 answers at the bottom. The agent even introduced the second set with: “Same issue-by-issue answers as above, repeated here at the end for reviewers scanning from the bottom.” This was one of many examples of unnecessary repetition.

Measuring word counts helped us find repetition, but couldn’t tell us whether a description explained the change. To assess that, we built a PR description quality checker using GPT-6 Sol and ran it on descriptions from the five weeks before we introduced the skill. We gave it each PR’s title, description, diff, and recorded results of automated GitHub checks, then asked it to evaluate four criteria:

Most descriptions were easy to follow: 97.6% received Good for Readability. But only 60.5% received Good for Explanation, and 11.7% contained unnecessary repetition or tangents. For Accuracy, the PR description quality checker flagged at least one contradicted claim in 34.5% of descriptions with valid results.

We needed our writing standard to address all three problems: repetition, missing context, and claims that contradicted the supplied evidence.

The full rating definitions are in Appendix C.

2. What makes a helpful PR description?

• The problem. What needs to change, and why? Who is affected by the bug, what is too slow, or what should a new feature let someone do?
• The solution. How does the PR address the problem? Explain the resulting behavior and decisions or trade-offs a reviewer needs to understand.
• Testing. How was the change checked? State what the tests or manual checks establish and what still needs verification.

An unhelpful, sloppy PR description:

• Uses more words than needed to explain the change.
• Gives a simple fix the same lengthy treatment as a complex change.
• Repeats the same information under different headings.
• Buries the problem, solution, and testing details in commentary that adds little to a reviewer’s understanding.
• Includes contradictory or incorrect statements about the PR.

3. Enforcing helpful PR descriptions

We found a useful starting point in ASD-STE100, or Simplified Technical English, a writing standard developed for aerospace documentation. Its rules help readers follow an instruction and understand when it applies. That includes keeping sentences short, using consistent terms, and stating a condition before the instruction it qualifies. The open-source SimpleEnglish project turns these principles into a skill: instructions an agent loads for a writing task.

We built three things to adapt it to our codebase and test how well it worked:

1. A version of the SimpleEnglish skill for PR descriptions, asking agents to clearly explain the impact of the PR, describe how it works, and include testing steps.
2. A prose linter: automated checks that give agents specific feedback on their drafts. It flags sentences over 30 words, filler expressions such as “robust,” and Latin abbreviations such as “e.g.” It also warns when a description is long overall or relative to the diff.
3. A PR description quality checker: We used GPT-6 Sol with the four criteria above to check whether descriptions explained the change and matched the code.

The PR description from the first section passed the linter’s sentence checks, but the PR description quality checker flagged its repeated explanations. The following rewrite passed all sentence checks:

4. What improved and what still needed work

We compared descriptions written before the skill was available with descriptions written after rollout, using the same linter and PR description quality checker for both groups.

Descriptions became shorter and less repetitive

Median length fell from 226 to 163 prose words, a 28% reduction, even as the median diff grew. The sentence-check pass rate rose from 38.6% to 98.3%.

The share rated Mixed or Poor for Concision fell from 11.7% to 4.6%, a 61% reduction. Descriptions were shorter, and the PR description quality checker was less likely to find repetition or tangents. Both improvements remained when we compared periods with the same mix of diff sizes.

However, clearer prose still left gaps

After rollout, 62.0% of descriptions explained the change and its context well enough to receive Good for Explanation, compared with 60.5% before.

However, even among descriptions that passed the linter, 37.8% received Mixed for Explanation: the PR description quality checker could follow the main change, but an important detail was missing or unclear.

The PR description quality checker also checked whether claims about behavior, scope, and testing matched the supplied evidence. It flagged at least one contradiction in 34.5% of descriptions before rollout and 32.4% afterward, among those with valid Accuracy results.

One example PR changes how long background scans waited to send diagnostic data before exiting:

In the PR, if a relaunch failed, the code used the shorter timeout. The description left out that exception, making it sound as though every background scan kept the longer wait. Our writing rules told agents how to write concisely, but didn’t ask them to check whether their explanation matched the code.

So.... we fixed it

We added this rule to the skill:

Before finalizing the description, compare it with the diff. Check whether it explains the changed behavior, including conditions or exceptions that affect how a reviewer should evaluate it. Add missing details that matter, remove unsupported claims, and distinguish tests added from tests actually run. Keep the explanation proportionate to the change.

We then used Claude Opus 5.5 to rewrite the descriptions from the same group of PRs. Each rewrite used the updated skill, the original description, the diff, and available check results. The PR description quality checker evaluated the rewrites using the same rubric as before.

Good Explanation rose from 62.0% to 89.3%. Among PRs with valid Accuracy ratings for both versions, contradiction flags fell from 32.4% to 16.0%.

Here’s the rewritten version of the background-scan description above:

The rewrite includes the failed-relaunch exception, so a reviewer can understand when the shorter timeout applies.

The rewrites were 52% longer: median length rose from 163 to 248 prose words. They also received better ratings for Concision, with Good rising from 95.4% to 99.1%, and Readability, with Good rising from 98.6% to 99.7%.

This is what we wanted the skill to do: remove repetition while keeping the details someone needs to understand the change.

5. Applying the skill to open-source PRs

We wanted to test our skill on PRs that weren't authored by our own developers to see how it would work in the wild. Below we examine two open-source PRs with agent-generated descriptions: PowerToys #41454, authored by Copilot, and protomolecule #263, which credits Claude Code in its description and implementation commit. Both explained a narrow change across several overlapping sections.

Using the skill on a PowerToys grammar fix

The PowerToys PR changed “1 hours” to “1 hour” in the Awake tray menu. Its 30-line diff mostly added resource definitions and generated accessors. The description explained the grammatical error in its opening, Problem, Root Cause, and Impact sections.

The rewrite explains the resource change once, keeps the details about the other menu options, and says that the build was blocked. It went from 216 to 75 prose words, a 65% reduction. We removed repeated explanations of the grammar mistake while keeping the implementation and testing details.

Using the skill on a protomolecule dependency fix

The protomolecule PR fixed an Astro parser that ESLint, a code linter, couldn’t find when run from a project subdirectory. The fix made the parser an optional peer dependency: projects using Astro would install it at their workspace root. Its 60 changed lines included a 46-line release note. The description repeated the dependency change in its Summary, Solution, Changes, and Technical Details.

error  Parsing error: The keyword 'interface' is reserved

@robeasthope/eslint-config/
└── node_modules/
    └── astro-eslint-parser/  ← Installed here

{
  "peerDependencies": {
    "astro-eslint-parser": "^1.0.0",
    // ... other deps
  },
  "peerDependenciesMeta": {
    "astro-eslint-parser": {
      "optional": true
    }
  }
}

pnpm add -D -w \
  astro-eslint-parser \
  eslint-plugin-astro \
  eslint-plugin-import-x \
  # ... other plugins

The rewrite explains the dependency change once and keeps the installation and testing steps together. It also states that the original reported no completed test results, so the next engineer knows those checks still need to be run. It went from 283 to 148 prose words, a 48% reduction.

6. What we learned

The writing rules helped our agents produce shorter, less repetitive descriptions. Checking those descriptions against the code helped them include conditions they’d missed and correct claims that didn’t match the evidence. The resulting descriptions were sometimes longer, because they had more to explain.

This is one way we’re spending the time AI saves us: asking agents to do the extra work of checking their explanations before passing that work on to someone else.

You can try the skill in Appendix A and adapt it to your own workflow.

Appendix

A. The skill

---
name: corridor-deslop-pr-descriptions
description: >-
  Rules for writing a PR description in plain English.
  Read this BEFORE you write or edit one. Also use it when someone says a
  PR body is too long, hard to read, or sounds like AI: "the PR body is a wall
  of text", "write this in plain English". It covers short sentences, no hedges
  or filler, and the issue link and testing checklist every PR body needs.
  Check a draft with `pnpm run lint:prose`.
argument-hint: '[file or PR number to check; omit to apply while drafting]'
---

# Simple English for PR descriptions

These rules apply to PR descriptions.

## The rules

| Rule                          | Do this                                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Max 25 words per sentence** | Split longer sentences. Do not drop "the" or "that" to fit. The linter errors past 30.                           |
| **One idea per sentence**     | Two facts joined by an em dash or ", and" are two sentences.                                                     |
| **Condition first**           | "If the flag is off, the export is uncapped." Not "The export is uncapped if the flag is off."                   |
| **No hedges**                 | Use `must` for a requirement and `can` for a possibility. Delete `should`, `may`, `might`, `could`, and `would`. |
| **Simple past, active voice** | "We removed the column." Not "The column has been removed."                                                      |
| **One word per idea**         | Pick one of check, verify, confirm, validate, or ensure, and keep it. Do the same for config and settings.       |
| **No filler**                 | Delete `simply`, `robust`, `comprehensive`, `crucial`, `leverage`, `utilize`, `in order to`, and `prior to`.     |
| **No show-off words**         | Delete `load-bearing`, `plainly`, `quietly`, `byte-identical`, `carve-out`, and `provably`. Give the proof.      |
| **No Latin**                  | Write "for example" and "that is", not `e.g.` and `i.e.` List the items instead of `etc.`                        |
| **Code stays exact**          | Never change a name, path, flag, or quoted error. The linter counts each as one word.                            |

Keep every fact and number. Cut words, not facts.

## Lead with the result

Say what changed for the reader before you give a hash, a path, or a stack trace.

> **Before:** Query signature `b7872` runs a DISTINCT pre-query with a three-way join.
>
> **After:** Analytics for three teams have not refreshed in two days. One long rollup
> key stops the whole rollup. Query signature `b7872` is the cause.

## What a PR body needs

A reviewer reads the body to decide whether the change is safe to ship. Put the details
that decision needs up front.

1. What changed, in one or two sentences.
2. A link to the related issue.
3. A testing checklist.

Most PRs need about 100 words.
Leave out notes about how you got there. That means old attempts, pasted test output,
failures that were already on `main`, and a "what this PR does not do" section. Do not bold
the start of every bullet. End with one plain link to the agent session, if there is one.

## Check the explanation against the diff

Before finalizing the description, compare it with the diff. Check whether it
explains the changed behavior, including conditions or exceptions that affect how a
reviewer should evaluate it. Add missing details that matter, remove unsupported
claims, and distinguish tests added from tests actually run. Keep the explanation
proportionate to the change.

## Check the draft

```bash
pnpm run lint:prose --pr <PR_NUMBER>                                # a PR on GitHub
pnpm run lint:prose body.md --pr-body --changed-lines 135    # a PR body before the PR exists
```

Run it before you mark the PR ready. If the body changes later, run it again before
merge. Fix every error. Warnings are your call. CI does not run it. Its tests are
`pnpm run lint:prose:test`.

## Attribution

Based on ASD-STE100 Issue 9, by way of
[AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish) (MIT). ASD-STE100 is a
registered trademark of ASD. This skill is not endorsed by ASD.

B. The linter

The linter checks both the total word count and the amount of explanation relative to the code change. It supplies two types of warnings:

• Length warning: more than 400 prose words.
• Density warning: at least 250 prose words and more than three prose words per changed line.

These warnings prompt an editing pass. A small security fix may need more explanation than a large, repetitive refactor, so the agent will still need to judge which details matter.

The linter also warns about repeated bold labels at the start of bullets, descriptions of abandoned attempts, long agent footers, and missing testing steps. It flags a fixed list of words, including “simply,” “robust,” and “provably.”

For example, suppose a change makes the client retry a timed-out upload up to three times:

Simply deleting “robust” would leave the behavior just as unclear. Our rewrite, on the other hand, clearly states what triggers a retry and how many retries the client allows.

C. The PR description quality checker