Your plan.md Needs a Devil's Advocate (and Codex Volunteers for the Job)

Have you ever written a technical plan at 11 PM, convinced it was flawless, only to realize the next morning you forgot authentication?

Happens to me. More than once. And the worst part isn’t the oversight—it’s that when you use AI to plan things out, the plan sounds so coherent your brain stops looking for flaws. Claude generates a document with sections, dependencies, execution order, and it all checks out. Seems like a senior engineer’s masterpiece. But nobody has challenged it.

Aseem Shrey published an article that nails this issue and proposes a solution I find elegant: have a second model review the first one’s plan. But not just once—on a loop until the reviewer says, “approved.”

The Problem: No One Challenges Your AI

When you rely on a single model to plan and execute, you end up with a coherent but unchallenged result. AI doesn’t contradict itself. It’s not going to say, “Hey, this authentication model is incomplete,” or “Your shell script quoting is broken.”

It’s like writing a document, reviewing it yourself, and thinking, “This looks great.” Of course it does—you wrote it. Pay attention here: peer review exists in science, engineering, and medicine for a reason. Not because the authors are dumb, but because creators are the worst reviewers of their own work.

I touched on this in my post about building my Jedi council for AI code review. But in that case, I talked about reviewing code. What Aseem is suggesting is to review the plan before writing a single line. It’s tackling the problem a step earlier.

How It Works: Claude Plans, Codex Reviews

The process is a simple Claude Code skill—a Markdown file, no infrastructure, no external services. When you call /codex-review:

1. Claude writes the plan to a temporary file.
2. The plan is sent to the Codex CLI in read-only mode (it can read your codebase for context but doesn’t make changes).
3. Codex reviews the plan and returns a verdict: VERDICT: APPROVED or VERDICT: REVISE.
4. If it says REVISE, Claude fixes and resubmits. The key trick: Codex resumes the previous session, so it remembers prior feedback and checks if the issues were truly fixed.
5. A maximum of 5 rounds are allowed. In practice, it usually takes just 3.

Think of it as a pull request between two AIs, where one proposes and the other pokes holes in it. No human intervention required.

14 Bugs in 3 Rounds

In the example from the article—a dashboard for a swarm of agents—the loop found 14 issues in the initial plan:

Round 1 (8 issues): No authentication for writable endpoints. Quoting bugs in shell scripts. Overlapping schema fields. Unbounded embedded arrays. No concurrency handling. Testing was limited to manual checks.

Round 2 (6 remaining issues): Non-atomic claims. Overly broad ACL permissions. Unspecified key rotation. Inconsistent state modeling.

Round 3: Everything resolved. Plan approved.

The before-and-after table speaks volumes:

From zero detected issues to fourteen caught and fixed. Without a human reading a single line of the plan.

Why Iteration Beats One-Off Reviews

A one-time review catches issues but doesn’t verify fixes. Aseem explains this well: iterative loops catch problems like, “I fixed one thing but broke something else in the process.”

This mirrors what happens in real-world code reviews. You tell someone, “This lock isn’t secure,” they fix it, and in doing so introduce a deadlock somewhere else. If you only check once, you miss it. Look twice, and you can catch it.

The technical detail that makes this work: Codex supports session resume. It doesn’t start fresh with every round. It remembers what it flagged, what it requested to be fixed, and checks that the fix actually works—not a quick hack that moves the problem elsewhere.

What I Want to Try

After reading the article, I’m itching to build something similar. I already use plan.md as a preliminary step for almost any serious feature, and so far I’ve been the one reviewing it. Which is basically to say: it hasn’t been reviewed, because when you’ve been deep in a Linear issue for three hours, your critical thinking is shot.

The idea of a /second-opinion feels natural. Not for everything—I’m not going to run three rounds of review for a CSS tweak. But for plans dealing with data models, authentication, concurrency, or anything that takes days to implement, having an autonomous adversary ask, “Hey, what happens if two agents try to claim the same resource at once?” could be invaluable.

What I love about this approach:

• It’s just a Markdown file. No server, no API wrappers, no exotic dependencies. A simple SKILL.md and you’re good to go.
• It’s on-demand. It doesn’t execute on every commit or every plan. You decide when it’s worth the extra effort. Keep pushing only when it matters.
• It’s adversarial by design. You’re not asking the reviewer to “look over the plan.” You’re asking it to find weaknesses. To try to break it. That intent makes all the difference.

The Elephant in the Room

Here’s the obvious question the article doesn’t fully answer: Do you specifically need Codex, or could any model work as the reviewer?

My gut says that what matters most is that it’s a different model. The value comes from diversity in biases. If Claude plans and Claude reviews, that’s like reviewing your own work—they share the same blind spots. Bringing a model with different training and heuristics into the mix is what creates the true “devil’s advocate” effect.

That said, the implementation with Codex CLI has one significant practical advantage: session resume. The reviewer remembering previous rounds is not just a nice-to-have—it’s what makes this a real loop of improvement rather than three separate reviews that repeat the same findings.

When Not to Use It

Aseem himself points this out: when speed matters more than thoroughness, it’s not worth it. A 3 AM production hotfix doesn’t need three rounds of adversarial review. It needs a patch, a test, and a deploy.

Likewise, for small plans—“add a field to a form”—the overhead probably isn’t worth it. My personal rule: if the plan is more than a page long, or impacts more than two modules, it’s worth a /second-opinion.

The Takeaway

What’s most interesting about this idea isn’t the technical implementation—it’s simple. It’s the mindset shift. Until now, the consensus was: “Use AI to plan, then execute the plan.” No one questioned the plan. The plan was sacred because it came from a “smart” model.

But an unreviewed plan is a plan full of latent bugs. Doesn’t matter if it’s written by GPT-4, Claude, Codex, or a senior engineer with two decades of experience. Without adversarial review—without someone asking, “What if this fails?”—you’re playing Russian roulette with complexity you can’t yet see.

One Markdown file. Two models. Three rounds. Fourteen fewer bugs. Not bad for something that fits in a gist.