Claude picks the first idea that works. Make it pick the best one.

Claude picks the first idea that works. Make it pick the best one.

⚡ TL;DR

Claude satisfices: the first workable approach it finds, it commits to.

That’s fine for straightforward tasks. For design decisions with high switching costs (architecture, data models, API surfaces), you want the best approach, not the first one that clears the bar.

Replan is a skill that forces the agent through iterative critique-and-refine loops. Each iteration generates alternatives, stress-tests assumptions, and checks in with you before converging. The result is a plan that’s been challenged from multiple angles before implementation begins. It ships for both Claude Code and Codex.

Want to skip the explanation? Jump to the setup prompt.

⚠️ The problem: satisficing

Herbert Simon coined “satisficing” in the 1950s: a portmanteau of “satisfy” and “suffice,” or choosing the first option that meets minimum criteria. It’s a rational strategy for humans with limited time and attention. It’s a terrible strategy for AI planning, where exploring alternatives costs seconds, not hours.

Your mileage may vary, but I’ve never seen Claude seriously consider alternative plans once it has one it thinks is viable. First workable plan wins. And if you suggested it, or even hinted at an implementation path, sycophancy drives Claude to make whatever you suggested into a workable strategy.

Claude Code’s plan mode (Shift+Tab twice) helps by making Claude research before acting, but it still thinks in a straight line: research, form opinion, write plan. One pass. No adversarial review of its own conclusions.

Replan breaks Claude out of this “first plan wins” local optimum and forces it to explore the design space more thoroughly.

🔄 How replan works

The core loop is simple: critique, generate alternatives, develop the best one, repeat.

  1. Understand & clarify. Read code and constraints. State assumptions. Ask questions before proposing anything. This prevents Claude from building an elaborate plan on a misunderstood requirement.
  2. Initial plan. A first draft, expected to be imperfect.
  3. Critique. Structured self-review: simplicity, maintainability, testability, hand-wavy gaps, unverified API assumptions. The specific critique questions matter. Without them, Claude produces vague critiques like “this could be more robust.” With them, you get “this assumes the Redis client handles reconnection, but I haven’t verified that.”
  4. Alternatives. Address the specific weaknesses found in step 3.
  5. Develop best alternative. Flesh it out to the same level of detail as the original. A hand-wavy alternative that “sounds simpler” isn’t a real comparison.
  6. Iterate. Repeat steps 3-5 at least three times, checking in with you between iterations. Without a floor, Claude will do one pass and declare it sufficient. Without user checkpoints, Claude converges on its own preferences instead of yours.
  7. Final plan. Cherry-pick the best elements from all iterations.

🙋 Checkpoints are where you add what Claude can’t grep for

The user checkpoints between iterations aren’t just for steering. They’re where you inject context Claude can’t find in the codebase: product goals, domain constraints, recent decisions from team conversations, regulatory requirements, upcoming migrations. Claude can read your code (and your technical project plans!), but it can’t read your roadmap or your Slack history. A plan built without that context may be technically sound and strategically wrong.

📋 The skill

The canonical source lives in our plugin marketplace: photostructure/coding-skills. Install the coding plugin in either product:

# Claude Code
/plugin marketplace add photostructure/coding-skills
/plugin install coding@photostructure

# Codex
codex plugin marketplace add photostructure/coding-skills
codex plugin add coding@photostructure

Use /coding:replan in Claude Code or $coding:replan in Codex. You can also type $ in Codex to pick the skill from the composer.

The heart of the skill is a seven-step process: understand & clarify → initial plan → critique → alternatives → develop best alternative → iterate (at least three times) → final plan. Each iteration presents options with pros/cons/risks and a recommendation. The marketplace file has the full text.

Replan is for thinking, not doing — the skill says so outright: “Treat the workflow as read-only: do not edit project files or begin implementation while replanning.”

That rule now lives in the instructions rather than in a tool allowlist. The earlier version pinned allowed-tools: Read, Glob, Grep, WebSearch in its frontmatter — Claude-Code-only, and it locked out the shell entirely.

Losing the allowlist turned out to be an upgrade, because a tool allowlist can only express capability, and the thing we actually care about is intent. So the skill now draws the line where it belongs:

Read-only commands are allowed, and encouraged, to settle an assumption the
plan rests on: `git log` for how a module got this way, `npm ls` for what is
actually installed, a small probe for whether an API behaves as assumed. An
unverified assumption is a risk you are handing to the implementer.

The line is intent, not tooling: run commands to _test the plan_, never to
_start building it_. "Let me just write a quick script to try this" is how
replanning turns into implementing.

An allowlist that forbids Bash can’t tell the difference between running git log to check an assumption and running npm test on code you just secretly wrote. A sentence can.

🔧 Adapting for your project

The skill is deliberately generic, and you tune it without forking it. Put your customizations in the project’s AGENTS.md (Claude Code will also honor CLAUDE.md); the skill reads them at the start of every invocation via its Required Reading step. Fork the skill and you inherit the maintenance forever.

Here’s what’s worth adding:

Point Required Reading at your docs. If your project has design principles or architecture docs, name them:

## Required Reading First

Before any work, you MUST read:

- [AGENTS.md](AGENTS.md)
- [CLAUDE.md](CLAUDE.md) (when present)
- [ARCHITECTURE.md](docs/ARCHITECTURE.md)

Every file listed here gets read at the start of every replan invocation, so keep the list short and high-value.

Add domain-specific critique prompts. The generic critique questions work, but project-specific ones are more powerful. Examples:

  • “Does this respect our backwards compatibility guarantees?”
  • “How does this affect cold-start latency?”
  • “Does this introduce new dependencies? Are they justified?”
  • “How does this interact with our existing caching layer?”

Write these into your AGENTS.md as standing critique questions. The skill’s generic ones (“Is it maintainable, testable, DRY, scalable?”) are a floor, not a ceiling.

Adjust the iteration count. Three is a minimum. For high-stakes decisions (database schema migrations, public API design), consider bumping to five. For lower-stakes decisions, three is fine. You can always ask for more iterations if the plan isn’t converging.

Name your design principles. The skill leans on Kent Beck; your team may not. If you follow hexagonal architecture, say so. If you have a style guide, reference it. The more specific the guidelines, the more specific the critiques.

Scope the read-only validation to your project. The skill already permits commands that settle an assumption. What it can’t know is which ones are cheap in your repo. If your test suite takes 20 minutes, say so, and name the fast subset worth running during planning. If there’s a scratch database or a staging endpoint that’s safe to probe, point at it. Otherwise the agent will either avoid verification it should be doing, or reach for something expensive.

🚀 Setting this up

Install the plugin:

# Claude Code
/plugin marketplace add photostructure/coding-skills
/plugin install coding@photostructure

# Codex
codex plugin marketplace add photostructure/coding-skills
codex plugin add coding@photostructure

Then use /coding:replan in Claude Code or $coding:replan in Codex. Start a new task after installation so the product reloads the plugin.

To tune it for your project, open your coding agent in the project directory, use its planning mode when available, and paste this prompt:

We installed the `coding` plugin from
photostructure/coding-skills. The bundled
`replan` skill is generic (`/coding:replan` in Claude Code,
`$coding:replan` in Codex).

Audit this project and propose project-specific tuning:

1. A "Required Reading First" section pointing to any
   existing project documentation (AGENTS.md, optional
   CLAUDE.md, architecture docs, design principles, etc.)
2. Domain-specific critique prompts based on this
   project's priorities (performance, backwards
   compatibility, security, etc.)
3. The actual design principles this project uses (not
   the generic Kent Beck reference)
4. Any concerns or constraints that should be part of
   every replan critique

Capture durable shared guidance in this project's AGENTS.md.
Also honor CLAUDE.md when present. Do not fork the skill.

🎲 Your mileage WILL vary

The iteration count, the critique prompts, the guidelines: these are starting points. Different models respond to instructions differently, and small changes in phrasing can produce very different results.

The core principle holds even if the details need tuning: force multiple passes of structured critique before committing to a design. The first idea is rarely the best idea. Make Claude prove it.