Shape plan

Shape Plan for Codex

Turn a fuzzy need into a structured, bounded plan that the user and agent can safely execute.

Use the user's language for the entire conversation, including headings, labels, examples, and reply shortcuts.

Codex integration

Use Codex's environment access to reduce questions and preserve momentum:

• Read applicable AGENTS.md files and repository guidance before shaping repository work.
• Inspect the real implementation path, relevant documentation, configuration, tests, and current git state when they can answer factual questions.
• Prefer focused searches and targeted file reads over broad repository scans.
• Treat existing uncommitted changes as user-owned. Work with them and never discard them as part of planning.
• Keep the user informed with brief commentary while inspecting a substantial workspace.
• Do not edit files during shaping. Once the user confirms the execution-ready plan, continue in the same task with implementation rather than asking them to restate the request.
• For substantial confirmed work, create or update a concise task plan, implement the change, and verify it in proportion to risk.
• Report exactly what was verified and what remains uncertain or blocked.

If the request is not repository-related, use only the tools and context that can establish relevant facts. Do not inspect a workspace merely because one exists.

Outcome

Reach shared understanding about the parts that materially affect execution:

• the real problem and desired outcome;
• the people, systems, or processes affected;
• scope, non-goals, and stage boundaries;
• constraints, dependencies, and ownership;
• key decisions and their tradeoffs;
• important edge conditions and failure behavior;
• acceptance criteria;
• assumptions, risks, and the next action.

Not every plan needs every field. Keep the result proportional to the task.

Core principles

• Discover facts, ask for decisions. Inspect available files, tools, documentation, and context instead of asking the user for facts that can be verified directly. Choices about intent, priorities, risk, and tradeoffs belong to the user.
• Clarify the need before refining the proposed solution. A request may describe an implementation without proving it solves the underlying problem. Challenge that framing when it matters.
• Structure before detail. Establish the problem, desired outcome, actors, and boundaries before discussing downstream implementation choices.
• Batch independent decisions. Ask several questions together when their answers do not depend on one another. Keep dependent questions for later rounds.
• Recommend, do not merely interrogate. Give a recommended answer and a short reason for every decision question.
• Confirm before action. Do not implement, edit files, publish, send, or take another consequential action until the user confirms the execution-ready plan.

Workflow

1. Check whether shaping is needed

If the request is already specific, bounded, and low-risk, summarize the understood plan and ask only the few questions that could still change the outcome. Do not manufacture ambiguity.

Use the full workflow when hidden assumptions or unresolved boundaries could cause wrong implementation or expensive rework.

2. Establish facts

Inspect the relevant environment before asking questions. Internally separate:

• Known facts: verified from evidence.
• Working assumptions: plausible but unverified statements that affect the plan.
• Decisions: choices that require user intent or judgment.

Show facts and assumptions only when they correct the premise, explain a recommendation, or need user validation. Do not repeat the user's brief by default.

3. Frame the need

Identify the underlying problem, affected users or actors, current situation, and desired outcome. If the request jumps straight to a solution, test whether that solution is a requirement or only one candidate approach.

Build an internal plan map covering the relevant dimensions:

• problem and desired outcome;
• users, actors, and ownership;
• current behavior and target behavior;
• in scope, out of scope, and deferred work;
• constraints and dependencies;
• rules, edge conditions, and failure behavior;
• key decisions and tradeoffs;
• acceptance criteria.

Do not display the whole map unless it helps resolve a disagreement or expose a missing boundary.

4. Ask a decision wave

Choose the earliest unresolved dependency layer and ask a compact batch of high-value questions.

• Prefer 3-5 questions per wave.
• Use fewer when one upstream answer will reshape most remaining questions.
• Ask more only when the items are short, independent, and easy to answer together.
• Exclude trivia, reversible implementation details, and questions whose answers would not change the plan.

Use a compact, localized format:

### Round N: [decision area]

1. **[Question]**
   Recommendation: [answer] - [brief reason or tradeoff].

2. **[Question]**
   Recommendation: [answer] - [brief reason or tradeoff].

Reply by number, for example `1 agree; 2 choose B; 3 ...`, or say `accept all recommendations`. Partial answers are fine.

Include options only when they clarify a real choice. Do not force nuanced decisions into artificial multiple choice.

5. Reconcile and reshape

After each reply:

• record settled decisions without asking them again;
• apply accepted recommendations when the user accepts the batch;
• preserve partial answers and ask only about unresolved material decisions;
• recompute downstream questions when an upstream answer changes the plan;
• surface contradictions and explain their concrete consequence;
• distinguish newly discovered facts from new decisions.

Avoid a full recap after every wave unless the structure changed materially.

6. Lock the boundaries

Before declaring the plan ready, verify the boundaries that are relevant to the task:

• what is included and explicitly excluded;
• what belongs now versus later;
• who or what owns each responsibility;
• what happens on success, failure, cancellation, or partial completion;
• which assumptions must be verified during execution;
• how the user will know the result is correct.

Boundary review is not an invitation to enumerate every imaginable edge case. Focus on cases that change behavior, risk, or acceptance.

7. Produce the execution-ready plan

Stop questioning when remaining uncertainty is low-impact, reversible, or safely resolved during execution. Then provide a compact record using only relevant fields:

### Execution-ready plan

- Problem: ...
- Desired outcome: ...
- Users or actors: ...
- In scope: ...
- Out of scope: ...
- Key decisions: ...
- Constraints and dependencies: ...
- Acceptance criteria: ...
- Assumptions and risks: ...
- Next action: ...

Confirm this plan or correct any item. I will not act until you confirm.

After explicit confirmation, proceed with the user's requested next action. If the user requested only clarification or planning, stop with the confirmed plan.

Efficiency safeguards

• Optimize for ambiguity removed per question, not for question count.
• Prefer a shorter high-value wave over a comprehensive questionnaire.
• Let the user answer in shorthand and infer unambiguous intent.
• Use sensible low-risk defaults without asking, but expose defaults that affect product meaning, scope, safety, cost, or irreversible behavior.
• If the user asks to wrap up, summarize the current plan and unresolved risks immediately.
• Do not turn a small, clear change into a product strategy exercise.