The Engineering of Intent, Chapter 25: The Debugging Playbook

This is Part 25 of a series walking through my book The Engineering of Intent. In the previous chapter, we catalogued what goes wrong in the process. Chapter 25 catalogs what goes wrong in the code — ten classes of bug and the investigation pattern that fits each.

A Flipbook, Not a Narrative

Use this chapter as a flipbook when a specific bug is in front of you. Each entry names the class, the typical symptoms, the investigation pattern, the prompts to use, and a worked example. I’ll list the ten here and quote a few of the worked examples.

The Ten Classes

1. Deterministic-But-Wrong — easiest class. Minimum repro + Bug-Hypothesis prompt + regression test.
2. Intermittent — gather pattern data before investigating. When it happens matters more than what fails.
3. Regression After Refactor — bisect, then compare line-by-line. The bug is almost always an unnoticed behavior change.
4. Only In Production — find the environmental difference. Reproduce the difference in staging.
5. Performance Regression — profile before hypothesizing. The bottleneck is rarely where you expect.
6. Concurrency Bug — do not trust your first intuition. Enumerate interleavings. Agents are unusually patient about this.
7. External-Service Bug — the third party’s docs are often wrong. Reproduce exact request/response.
8. Configuration Bug — diff the deployed config against the source. Agents are excellent at this.
9. Data-Shape Bug — sample the data. Look for nulls and extra fields you didn’t anticipate.
10. The “It Cannot Happen” Bug — the statement is wrong. Find out why. An agent will check the code, not the claim.

Two More Worked Examples

On Only In Production: a serialization bug that only occurred with records containing a specific unicode character. Staging didn’t have that record. Once we copied a minimal version with the character, staging reproduced. One-line encoding correction.

On Configuration Bug: an environment variable correct in staging and missing in production. The agent flagged it when given both templates side by side. Fix: one line added to the production template and a template-consistency test added to CI. The test costs nothing; the incident would have cost a weekend.

“The ‘it cannot happen’ bug is my favorite one to work on, because the team has told me multiple times that it cannot. Agents are useful here because they do not share your confidence — they will check the actual code rather than believing the claim. After a merger, a rare class of users had been migrated and now had two IDs, breaking an invariant the team had trusted for years.”

Next up — Chapter 26: Checklists for the Working Engineer. Chapters 23 to 25 gave patterns and playbooks. Chapter 26 gives the short-form artifacts I actually reach for mid-task — the pre-ship checklist, the review checklist, the incident checklist, and a few others that fit on one screen.