Plan before consequential implementation

Understand the approach

Plan mode gives Codex room to inspect context, ask about material ambiguities, and propose an approach before editing. In the app, /plan is a documented entry point; supported clients also expose planning controls. Use it when several implementation choices affect behavior, data, or maintenance. A clear single-file correction usually does not benefit from an elaborate planning phase.

A useful plan describes the starting state, intended behavior, constraints, affected areas, verification, and unresolved decisions. It should explain why the chosen approach fits, rather than merely listing generic development steps. Distinguish observation from assumption: a repository convention found in a file is evidence, while an inferred user preference should be labeled. The plan must preserve existing work and avoid broad unrelated changes.

In the app use /plan, with Shift+Tab available in supported clients; CLI users can also enter /plan. If the native control is absent, a written read-only request can still organize thinking but is not evidence of an enforced mode. Leave Plan mode deliberately before implementation, then run the checks against actual changed files. This lesson finishes with the extension artifact rather than stopping at an approval checklist.

Acceptance belongs in the plan

The missing-both change should return exactly missing-running and missing-verification, preserve the complete fixture's zero findings, and continue rejecting unknown IDs, extra arguments, and pre-readiness calls. The server enum follows the shared IDS export, while the headless review-result schema has a separate fixture enum that must also be updated. These concrete dependencies make a plan useful: a reviewer can evaluate the intended behavior before edits and repeat the same checks after implementation.

Try it step by step

1. Open the generated packageRoot and enter native Plan mode using /plan or its supported control; inspect the selected mode.
2. Send the bounded prompt, compare the plan with the actual package files and resolve any material ambiguity.
3. Revise a missing schema/version/check step before leaving Plan mode. Keep the output as a small implementation contract.
4. Leave Plan mode, request implementation, and run the original package’s extension/check.cjs against the generated workspace root.
5. Review the diff, run the copied baseline suite and compare with the complete solution in a second fresh workspace after your attempt.

A useful starting example

Illustration · adapt before use.

/plan

Plan the missing-both extension in extension/README.md for this generated package.
Inspect the checker allowlist, fixture, MCP enum, output schema and version fields.
Keep arbitrary paths rejected and preserve the three original results.
Name exact file changes and direct plus stdio checks. Do not implement yet.

Check your result

• The plan names the actual allowlist, fixture, output enum, server/package versions and verification commands.
• The implemented artifact passes the extension grader and original behavioral suite without weakening them.
• The final diff remains scoped; the readable reference is a comparison after an attempt rather than a fabricated model result.

Common mistakes

• Using planning as an endless substitute for producing the delegated result.
• Treating a plan-mode label as an enforced security boundary or authorization for live-system changes.