The Patch Letter Pattern: Make Your Assistant Write a Cover Letter Before It Touches Your Code

Source: Dev.to

Using a Patch Letter to Keep AI‑Assisted Code Changes Safe

When you ask an assistant to fix a bug, you often get more changes than you expected – some great, some… creative.
The fastest way to avoid surprise refactors isn’t a bigger model or a longer prompt; it’s a tiny workflow change:

Before the assistant edits code, make it write a patch letter – a short “cover letter” that describes the proposed change as if it were a pull‑request description.
Review the patch letter like a spec. Only after you approve it do you ask for the implementation.

The Two‑Step Loop

It’s boring. It’s also ridiculously effective.

A patch letter forces the assistant to commit to specifics in text:

• What exactly will change?
• Which files will be touched?
• What won’t change?
• What’s the risk surface?
• How will we test it?

Most AI‑assisted coding failures are really planning failures – the assistant starts writing before the problem is framed tightly enough. A patch letter makes the plan reviewable.

Patch Letter Template (10–25 lines)

Summary (1–2 lines): what will be different for users/systems
Motivation: why this change is needed
Approach: the implementation strategy (high level)
Files/Modules touched: list, with purpose
Non‑goals: what we will not do in this patch
Risk & rollout: what could break, how to mitigate, rollback notes
Test plan: the checks you will run (and which tests you’ll add)
Open questions: anything that needs a decision before coding

You can paste the patch letter directly into a PR description later.

Ready‑to‑Copy Prompt

You are helping me with a code change. **Do NOT write code yet.**

Write a patch letter (like a PR cover letter) for the change below.

Context:
- Repo: [language/framework]
- Constraints: [time budget, style guide, perf, backward compatibility]
- Target behavior: [what should happen]
- Current behavior: [what happens today]
- Evidence: [logs, stack trace, failing test, reproduction steps]

Requirements:
- Keep it under 25 lines.
- Include: Summary, Motivation, Approach, Files touched, Non‑goals, Risks, Test plan, Open questions.
- Be specific: name the likely modules/files and the key functions/areas.

Change request:
[describe the change]

The key line is **“Do NOT write code yet.”**  
You’re not banning code forever – you’re sequencing it.

Example Walk‑through

Scenario: An API endpoint returns paginated results. Users report missing items on page=2 with certain filters.

Context:
- Repo: Node.js + Express + PostgreSQL
- Constraints: no breaking response changes; keep query fast; do not change DB schema
- Target behavior: pagination is stable and deterministic
- Current behavior: items can be skipped or duplicated between pages
- Evidence: QA repro — filter=active, sort=updatedAt desc

Change request:
Make pagination stable when sorting by updatedAt, even when multiple rows share the same timestamp.

A solid patch letter

Summary: Make /items pagination deterministic by adding a stable tie‑breaker to the sort.

Motivation: When multiple rows share `updatedAt`, offset/limit with a non‑unique ORDER BY can skip/duplicate rows across pages.

Approach: Keep primary sort `updatedAt DESC`, add `id DESC` as a secondary key; ensure cursor/offset logic matches the composite order.

Files touched:
- src/routes/items.ts (handler)
- src/db/itemsQuery.ts (query builder)
- tests/items.pagination.test.ts (new regression tests)

Non‑goals: No schema changes; no new pagination API; no changes to response shape.

Risk & rollout: Existing clients relying on implicit ordering may see a different (but now deterministic) item order for equal `updatedAt`.

Test plan: Add regression test with fixture rows sharing `updatedAt`; verify page 1 + page 2 contain all IDs exactly once; run full test suite.

Open questions: Are we using offset pagination or cursor pagination today? If cursor, what field(s) are encoded?

What this accomplishes

• Explains why the bug happens.
• Names the likely files to edit.
• Calls out non‑goals so you don’t get a stealth refactor.
• Surfaces the one thing that matters before coding: offset vs. cursor.

At this point you can answer the open question, adjust the plan, and approve the patch letter. Then ask the assistant to implement the change.

Rules for the Assistant (once the patch letter is approved)

1. Stay within the Non‑goals.
2. If you discover you need to violate a Non‑goal or touch additional files, STOP and propose an updated patch letter first.
3. After the code, output a short checklist matching the Test plan.
4. (Optional) After implementing, provide a 10‑line diff summary before showing the full code – a second review checkpoint for large patches.

When to Use a Patch Letter

• Multiple files are touched.
• Logic or queries are changed.
• The change could cause scope creep.

If you’re doing a tiny, local change (rename a variable, fix a typo), a patch letter is overkill.

TL;DR

1. Ask for a patch letter first.
2. Review & approve it.
3. Then ask for the implementation.

This creates a clean “contract”: the assistant can move fast, but it can’t silently expand scope. The patch letter often ends up being 80 % of a great pull request – clear summary, rationale, explicit risks, and tests – leaving only the actual code to be added.

break production,
…the patch letter costs you ~60 seconds and saves you an hour of review.

The Patch Letter Pattern

1. Make the plan reviewable.
2. Approve the plan.
3. Write the code.

It’s the easiest way I know to keep AI‑assisted coding fast and sane.

Try it:
Start with one place—your next bug‑fix PR. Ask for a patch letter first, and you’ll feel the difference immediately.