We Wrote the 'Perfect' Concise PR — and Watched an Agent Break the Wrong Service

Why This Matters

Here's the thing nobody tells you: 'be concise' was never a virtue. It was a shortcut that worked because your reader was human. The moment an agent with zero memory of your codebase opens that PR, concise becomes a bug — and it'll cost you long before you figure out why. Day 10 is about naming that shift before it quietly rewires your habits without asking.

The Stall

Last month, one of our agents picked up a PR titled 'Fix retry logic.' The description: 'Retries were double-firing under load. Fixed the race. See ticket for context.' A human teammate reads that in two seconds flat and fills in the rest — remembers the incident channel, knows which service, has already seen the ticket. The agent had none of it. First move: grep the whole repo for 'retry,' open four files that had nothing to do with the bug, and propose a fix to the wrong service's backoff config. Not because it's dumb. Because the description assumed a shared memory that, on its side, simply doesn't exist.

The Old Rule: Assume Shared Context, Write Less

For years, good PR writing meant cutting. You wrote for a reviewer who'd sat in standup, seen the Slack thread, already carried the mental model of the service in their head. Trimming the description was a form of respect — you didn't restate what everyone in the room already knew. That rule held up because the reader was never truly stateless. Even a reviewer seeing the PR cold could ping you, or dig through history, and reconstruct your intent in a couple of minutes.

Why Agents Break the Assumption

An agent opening your PR has no memory of yesterday's conversation, no hallway aside, no Slack thread to check unless you physically paste it in. Every session starts at zero. This isn't a bug to write around — it's the actual operating condition now. Whatever context didn't make it into the PR description doesn't exist for that reader, full stop, no matter how obvious it felt to you when you wrote the code.

• ▹No session memory — yesterday's agent and today's agent share no state unless it's written into the artifact itself
• ▹No social inference — it has no way to know 'the usual approach' means the pattern from three PRs back
• ▹No cost to guessing — a human would Slack you a quick question first; an agent just guesses, confidently, and acts on it
• ▹No shared incident history — 'the race from before' means nothing without the actual mechanism spelled out

The Rewrite

So we changed the target reader. We now write PR descriptions as a context dump for someone with zero memory. Four sections became mandatory: why, what was tried, what NOT to do, and constraints.

BEFORE:
---
Fix retry logic

Retries were double-firing under load. Fixed the race.
See ticket for context.

AFTER:
---
## Why
Under load (>200 req/s), the order-service retry wrapper
and the queue consumer's own retry were both firing for the
same failed job, causing duplicate charges. Root cause:
retry wrapper didn't check the idempotency key before
re-enqueuing.

## What was tried
- First attempt: added a mutex around the enqueue call.
  Rejected — this serializes all jobs, kills throughput.
- Second attempt (this PR): check idempotency key in Redis
  before retry, skip if already processed.

## What NOT to do
- Do not remove the queue consumer's retry — it's the only
  safety net if Redis is down. Removing it caused a full
  incident in staging (see #482).

## Constraints
- Redis lookup must stay under 5ms p99 (this path is on the
  hot loop for order processing).
- Must work with the existing idempotency key format
  (order_id + timestamp bucket), not a new scheme.

The Uncomfortable Part

By old standards, that second version is worse writing — longer, less elegant, restating things any senior engineer would infer in half a second. That discomfort is the tell you're doing it right. You've stopped writing for the smartest possible reader and started writing for the most literal one. The tradeoff holds because the cost of an agent guessing wrong — touching the wrong service, ripping out a safety net, blowing past a hard constraint — is way higher than the two extra minutes it takes you to spell it out.

The Test for Tomorrow

Before you mark a PR description 'done,' run this test: could an agent with zero memory of this repo pick it up without going off the rails? Not 'would a smart engineer get it' — would a stateless one. If your answer leans on 'well, they'd ask' or 'they'd check the ticket,' it fails. So paste the ticket. Spell out the approach you rejected. Name the exact thing not to touch.

Where This Fits

The skill here isn't brevity — it's context-transfer: packing everything a stateless reader needs into the artifact itself, every single time. Tomorrow builds straight on top of this. Once you can write a PR an agent can safely act on, the next skill is reviewing what it hands back to you — and knowing which parts of that output deserve the same scrutiny you'd give a junior engineer's first PR.

Extend your knowledge

• ▹Pull your last 3 merged PRs and run them through the zero-memory test — rewrite whichever one fails
• ▹Hand a real agent (Claude Code, Cursor, whatever you use) the same PR before and after this rewrite, and watch how its first move changes
• ▹Check how your team writes incident postmortems — the same context-transfer discipline (why, what was tried, what not to repeat) belongs there too
• ▹Preview: Day 11 is about reviewing agent output — what to scrutinize versus what to trust, once your input side is solid