Codex Prompt Optimize

Intercept low-quality prompts before execution. Analyze user intent, infer missing structure, and emit a well-formed Codex prompt — then execute the task using that prompt.

When to Activate

Activate when the raw input matches two or more of these signals:

Do not activate when:

• The prompt already contains a clear goal + scope + done-state, even in plain language.
• The user explicitly asks to explore or brainstorm (open-ended intent is the goal).
• The prompt is short but unambiguous (e.g., "run tests" or "format src/app.ts").

Analysis Protocol

Extract four dimensions from the raw input. Mark each as present, inferable, or missing.

1. Intent — Map to: Diagnosis, Implementation, Fix, Review, Refactor, or Research.
2. Scope — Target files, directories, modules. Extract @file mentions and paths. If uninferrable, flag as missing.
3. Constraints — Check AGENTS.md, conversation context, language/framework conventions.
4. Done-State — What success looks like. Infer from intent category if unstated. If uninferrable, ask one targeted question — never more than one.

Prompt Assembly

Build the optimized prompt using XML blocks. Always include <task> and <defaultfollowthrough_policy>. Add conditional blocks by intent category:

Optimization rules:

1. One task per prompt — split mixed asks, optimize the first, queue the rest.
2. Prefer contracts over nudges — "verify against requirements" beats "try really hard."
3. Keep the output contract minimal — ask only for what the user will use.
4. Never inflate complexity — if <task> alone is sufficient after rewriting, skip optional blocks.
5. Preserve user vocabulary and anchor to actual repo paths from AGENTS.md.

Execution Flow

User input → Quality gate (≥2 signals?) ─── No ──→ Pass through
                    │ Yes
                    ▼
            Extract 4 dimensions
                    │
                    ▼
            Any uninferrable? ─── Yes ──→ Ask ONE question
                    │ No
                    ▼
            Assemble XML prompt
                    │
                    ▼
            Emit summary → Execute

Summary output before executing:

Prompt optimized: [what was clarified]
Intent: [category]  Scope: [files/modules]  Done: [criteria]

Proceed immediately. Do not ask for approval unless a clarifying question was needed.

Reusable XML block templates live in [references/prompt-blocks.md](references/prompt-blocks.md). End-to-end optimization examples live in [references/optimization-recipes.md](references/optimization-recipes.md). Common anti-patterns to detect and correct live in [references/anti-patterns.md](references/anti-patterns.md).