Stop Re-Running Codex on Errors: A 4-Step Debugging Routine That Actually Converges

When Codex hits an error, most people's first instinct (mine included) is to paste the error back and run it again. Sometimes the second try works. Sometimes you burn six cycles on the same failure and end up exactly where you started.

After a few months of daily Codex use, I settled on a four-step routine that converges almost every time.

Step 1: Make it classify before it fixes

Paste the full error and add:

Don't change any code yet. Classify this error: is it an environment problem (dependencies, versions, paths), a logic problem in the code, or a problem with how I described the task? Give me your reasoning.

Codex's default bias is to change code to accommodate the error. But a large share of errors aren't the code's fault at all — a missing dependency, a wrong runtime version, an unset env var. Editing code to "fix" those just buries the real problem.

Step 2: Ask for a minimal reproduction, not a fix

Give me the smallest snippet that reliably reproduces this error. Only what's needed to trigger it.

Writing the minimal repro often exposes the bug by itself: an input that upstream code mutated, a config value that differs from what you assumed. Comparing the repro against the real code narrows the search space from "somewhere" to a specific block.

Step 3: Test one hypothesis at a time

List the likely causes in order. Change only the most likely one, run the check, and report back before touching anything else.

Changing three suspects at once might make the error disappear — and teach you nothing. Next time the same class of bug shows up, you'll be guessing from zero again.

Step 4: Make it explain why the bug happened

Summarize: the root cause, why this change fixes it, and what to watch for in similar code.

A fix that can't be explained is usually a coincidence that will resurface. The explanation also doubles as documentation — I append these summaries to the project's AGENTS.md, so the repo accumulates its own troubleshooting handbook over time.

The pattern underneath

Errors aren't the expensive part. Re-diagnosing the same error from scratch is. Classify first, change one thing at a time, and make every fix leave a written reason behind.

I write about practical ChatGPT and Codex workflows. More notes on my profile.