gpt-5-5-prompt-writer

GPT-5.5 Prompt Writer

Write one prompt that a GPT-5.5 session can execute with minimal ambiguity. Optimize for outcome, action, persistence, and verification, not for prose elegance.

Read references/openai-gpt-5-5-prompting.md when the task is long-horizon, tool-heavy, or expensive enough that prompt quality materially matters.

Workflow

1. Capture the real task.
2. Identify the execution environment (Codex CLI, Responses API, Agents SDK, custom harness).
3. Define hard constraints and done criteria.
4. Decide which Codex-style XML blocks the task actually needs.
5. Write the prompt as block-structured XML with an outcome-first task statement.
6. Add a verification loop and completeness contract for execution prompts.
7. Recommend reasoning.effort and text.verbosity deliberately.
8. Remove vague or contradictory instructions.

Capture The Real Task

Before drafting, extract:

• The objective: what must be changed, fixed, implemented, or reviewed.
• The environment: repo path, branch, services, runtime, tools available, secrets assumptions.
• The constraints: files or systems that must not be touched, style rules, required docs, approval limits.
• The validation surface: tests, build, lint, integration suites, smoke checks, manual verification, or whatever the project actually uses. Let the user name their own checks.
• The completion rule: what must be true before GPT-5.5 may stop.

If the user supplied a spec or earlier review findings, turn those into explicit required work items in <task>. Do not leave them implicit.

Prompt Shape

GPT-5.5 prompts compose from named XML blocks. Use only the blocks the task needs.

Core wrapper:

• <task> — the concrete job, the relevant repo or failure context, and the expected end state.

Output and format:

• <structured_output_contract> — exact response shape and ordering.
• <compact_output_contract> — concise prose contract when no schema applies.

Follow-through and completion:

• <default_follow_through_policy> — when to act vs ask.
• <completeness_contract> — finish the job, do not stop at first plausible answer.
• <verification_loop> — verify result before finalizing, fix and rerun if a check fails.

Grounding:

• <missing_context_gating> — do not guess; retrieve or state what is unknown.
• <grounding_rules> — anchor every claim to context or tool output, label inferences.
• <citation_rules> — back claims with primary sources where research applies.

Safety and tool use:

• <action_safety> — keep changes tightly scoped, flag risky actions.
• <tool_persistence_rules> — keep using tools until enough evidence to finish.

Task-specific:

• <research_mode> — separate facts, inferences, open questions.
• <dig_deeper_nudge> — check for second-order failures before finalizing.
• <progress_updates> — brief, outcome-based progress for long runs.

Use short imperative bullets inside each block. Keep the prompt concrete.

Model-Specific Rules

Apply these GPT-5.5-specific patterns:

• Outcome-first. Describe the destination, not every step. GPT-5.5 picks better paths than micromanaged hidden algorithms.
• Literal instruction following. GPT-5.5 interprets prompts in a literal and thorough manner, so define success criteria explicitly. Replace "ALWAYS X, THEN Y" absolutes with decision rules: "If X, do Y; otherwise Z."
• Reasoning effort. Recommend reasoning.effort: "medium" as the interactive coding default. Use "low" for latency-sensitive work where some thinking still helps. Reserve "high" or "xhigh" for complex agentic tasks where evals show measurable gains. Use "none" only for fast, no-reasoning paths (classification, voice). Higher effort is not automatically better; tighten the prompt before raising effort.
• Verbosity. Recommend text.verbosity: "low" for code agents and concise responses; the API default "medium" is often too long. Specify word budgets, section counts, or JSON-only when strictness matters.
• Bias to action. "Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes." Add this verbatim to long-horizon coding prompts.
• Tool preference. Prefer dedicated tools over raw shell (e.g., apply_patch, rg, read_file, list_dir, update_plan) for Codex runs. Parallelize independent tool reads.
• Planning. For medium-or-larger tasks in Codex, instruct the model to maintain a plan via update_plan. Skip planning for trivial tasks. Before finishing, reconcile every plan item — Done, Blocked, or Cancelled. Never leave items in-progress.
• Structured outputs. Do not describe schemas in prose. Use the Structured Outputs API for validation. Tell the model to "return exactly the requested output shape and nothing else."
• Prompt caching. Place static content first, dynamic content last. Use prompt_cache_key consistently for repeated traffic. Track usage.prompt_tokens_details.cached_tokens.
• No assumed tech stack. Use what the user named. If the user did not mention Docker, do not write "Start local Docker services". The validation block must reflect their stack, not a default one.

Execution Loop

For long-running coding prompts, include a loop in the prompt:

1. Read the relevant repo instructions and source files first.
2. Build a concrete implementation plan from the actual code, not assumptions.
3. Make the smallest correct change set that resolves the required items.
4. Run the required validations.
5. If validation fails, fix the cause and rerun until green or until blocked by a real external dependency.
6. Reconcile every plan item before finishing.
7. Do not stop at partial implementation or analysis-only output.

Validation Rules

Name the exact commands and required services. Good prompts do not say "test thoroughly"; they say exactly what must run.

For tasks with local infrastructure, spell out startup expectations using whatever the project actually uses, named by the user, not assumed:

• Start any required services (databases, queues, container runtimes, dev servers).
• Apply any required schema or data migrations.
• Start any worker or background processes the workflow depends on.
• Run end-to-end or browser checks only against the correct local environment.

If the prompt requires running multiple services or end-to-end checks, say that success is not complete until those paths have been exercised and any failures addressed or reported with evidence.

Template

<task>
You are an autonomous senior engineer working in {{repo_path}} on branch {{branch}}.
Implement the required work items end-to-end and validate them.

Required work items:
- {{item_1}}
- {{item_2}}

Relevant files and docs:
- {{file_or_doc_1}}
- {{file_or_doc_2}}

Tech stack: {{stack_named_by_user}}.
</task>

<default_follow_through_policy>
Default to the most reasonable low-risk interpretation and keep going.
Only stop to ask when a missing detail changes correctness, safety, or an irreversible action.
</default_follow_through_policy>

<completeness_contract>
Persist until the task is fully handled end-to-end within the current turn whenever feasible.
Do not stop at analysis or partial fixes.
Treat the task as incomplete until every required item is covered or explicitly marked [blocked] with evidence.
Before finishing, reconcile every plan item: Done, Blocked, or Cancelled. Never leave items in-progress.
</completeness_contract>

<tool_persistence_rules>
Prefer dedicated tools over raw shell (apply_patch, rg, read_file, list_dir, update_plan).
Parallelize independent reads; sequence dependent ones.
After parallel retrieval, synthesize before the next batch.
Keep using tools until you have enough evidence to finish confidently.
</tool_persistence_rules>

<verification_loop>
Required validations:
- {{command_1}}
- {{command_2}}
- {{service_or_environment_named_by_user}}
Before finalizing, run the required validations.
If a check fails, fix the cause and rerun until green or a real external blocker remains.
</verification_loop>

<missing_context_gating>
Do not guess missing repository facts.
Retrieve with tools, or state exactly what remains unknown.
</missing_context_gating>

<action_safety>
Keep changes tightly scoped to the stated task.
Avoid unrelated refactors, renames, or cleanup unless required for correctness.
Do not run destructive git commands (reset --hard, checkout --) without explicit approval.
No broad try/catch; propagate errors explicitly. No `as any` or type assertions in place of real types.
</action_safety>

<structured_output_contract>
Final report:
1. what changed (per file, one line each)
2. what validations ran and their outcomes
3. residual risks or follow-ups
Keep it compact. Highest-value findings first.
</structured_output_contract>

Suggested API or CLI configuration:

• model: "gpt-5.5"
• reasoning.effort: "medium" (use "high" only if evals show measurable gains)
• text.verbosity: "low"
• Use the Responses API for reasoning, tool-calling, and multi-turn workflows.
• For Codex CLI: run with codex exec for non-interactive automated runs (or just codex for an interactive TUI session) and let the harness manage tools and planning.

Anti-Patterns

Avoid these prompt mistakes:

• Vague goals with no acceptance criteria.
• Step-by-step micromanagement when the path does not actually matter — use outcome-first instead.
• Absolute commands ("ALWAYS", "NEVER") for judgment calls — use decision rules.
• Asking for persistence without naming the validation loop.
• Asking for tool use only indirectly when tool use is actually required.
• Overstuffing the prompt with background that does not change execution.
• Mixing contradictory instructions like "be extremely proactive" and "only use tools when absolutely necessary" without task-specific guidance.
• Letting the model decide whether validation matters.
• Raising reasoning.effort to compensate for a weak prompt — overthinking is real on GPT-5.5.

Final Check

Before returning a prompt, verify that it:

• names the exact implementation scope inside <task>
• names the exact validation commands inside <verification_loop>
• names any required services or environments and how to start them, in the user's stack only
• includes <completeness_contract> for execution work
• includes <missing_context_gating> whenever guessing would be costly
• replaces absolute commands with decision rules where appropriate
• recommends a deliberate reasoning.effort and text.verbosity
• does not stuff schema descriptions in prose when Structured Outputs would do the job
• tells GPT-5.5 what counts as done
• uses no tech-stack names the user did not mention