codex-simplify-plan

name

codex-simplify-plan

description

Review current code changes for reuse, quality, and efficiency, then write a simplify implementation plan instead of modifying code. Use when the user wants simplify-style investigation first but explicitly wants a plan, a plan-only pass, a planning mode run, or a markdown implementation plan in the current workspace rather than immediate code changes. In Codex, always launch three parallel explorer subagents with the full diff, using model gpt-5.4 and reasoning_effort xhigh, then synthesize their findings into a single plan document.

Codex Simplify Plan

Overview

Review changed code through the same three simplify lenses as codex-simplify, but stop before implementation. After all three review agents finish, write a Markdown implementation plan in the current workspace instead of modifying code.

Phase 1: Identify Changes

Run git diff or git diff HEAD if there are staged changes to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.

Capture the diff text and keep it available for the three review agents so each agent sees the same full context.

Phase 2: Launch Three Review Agents in Parallel

Use Codex native agents to launch all three review agents concurrently in a single wave. Use multi_tool_use.parallel to issue all three spawn_agent calls together so they start at the same time.

For each agent:

• Use agent_type: "explorer".
• Use model: "gpt-5.4".
• Use reasoning_effort: "xhigh".
• Pass the full diff so the agent has complete context.
• Ask for findings only, not patches.

After spawning:

• Do not send nudges just to make an agent finish faster.
• Do not use send_input or interrupt: true unless the task itself changed and you need to redirect the agent.
• Do not busy-poll with repeated short wait_agent calls.
• If you are blocked on the results, use wait_agent with a long timeout and let the agents finish at their own pace.

Agent 1: Code Reuse Review

For each change:

1. Search for existing utilities and helpers that could replace newly written code. Look for similar patterns elsewhere in the codebase. Common locations are utility directories, shared modules, and files adjacent to the changed ones.
2. Flag any new function that duplicates existing functionality. Suggest the existing function to use instead.
3. Flag any inline logic that could use an existing utility. Hand-rolled string manipulation, manual path handling, custom environment checks, and ad-hoc type guards are common candidates.

Agent 2: Code Quality Review

Review the same changes for hacky patterns:

1. Redundant state: state that duplicates existing state, cached values that could be derived, observers or effects that could be direct calls
2. Parameter sprawl: adding new parameters to a function instead of generalizing or restructuring existing ones
3. Copy-paste with slight variation: near-duplicate code blocks that should be unified with a shared abstraction
4. Leaky abstractions: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
5. Stringly-typed code: using raw strings where constants, enums, string unions, or branded types already exist in the codebase
6. Unnecessary JSX nesting: wrapper elements that add no layout value when inner props already provide the needed behavior

Agent 3: Efficiency Review

Review the same changes for efficiency:

1. Unnecessary work: redundant computations, repeated file reads, duplicate network or API calls, N+1 patterns
2. Missed concurrency: independent operations run sequentially when they could run in parallel
3. Hot-path bloat: new blocking work added to startup or per-request or per-render hot paths
4. Recurring no-op updates: state or store updates inside polling loops, intervals, or event handlers that fire unconditionally. Add a change-detection guard so downstream consumers are not notified when nothing changed. Also verify wrapper helpers honor same-reference returns or the local no-change convention.
5. Unnecessary existence checks: pre-checking file or resource existence before operating. Operate directly and handle the error instead.
6. Memory: unbounded data structures, missing cleanup, event listener leaks
7. Overly broad operations: reading entire files when only a portion is needed, loading all items when filtering for one

Phase 3: Write The Plan Document

Wait for all three agents to complete. Aggregate their findings into one coherent view of the change set. If a finding is a false positive or not worth addressing, note it and move on. Do not argue with the finding, just skip it.

Do not modify repository files other than the plan document, do not implement fixes yet, and do not drift back into patching mode.

Treat the rest of the task as read-only apart from the plan document. Use update_plan to track the planning steps.

Write a single implementation plan document at ./codex-simplify-plan.md in the current workspace. If ./codex-simplify-plan.md already exists, update it in place rather than creating duplicates. Use apply_patch to create or update the plan document.

The plan document must cover the whole simplify pass rather than isolated findings. It should describe what to change, what to leave alone, what existing helpers or abstractions to reuse, how to sequence the edits, and how to verify the result.

Use this structure for ./codex-simplify-plan.md:

# Plan

<1-3 sentences describing the simplify goal, the main cleanup themes from investigation, and the overall implementation approach.>

## Scope
- In:
- Out:

## Action items
[ ] <Concrete simplify step 1>
[ ] <Concrete simplify step 2>
[ ] <Concrete simplify step 3>
[ ] <Concrete simplify step 4>
[ ] <Concrete simplify step 5>
[ ] <Concrete simplify step 6>

## Open questions
- <Only if needed>

Good plan items are grouped around the real cleanup work surfaced by the three agents:

• reuse substitutions
• abstraction cleanup
• deletion or consolidation of duplicate logic
• efficiency fixes
• narrow verification

Do not mix implementation with planning. The response should say that the plan document was written or updated and give its path, not claim that code changes were made.