OpenAI tells devs: don't port GPT-5.4 prompts to GPT-5.5, rebuild from scratch

OpenAI shipped GPT-5.5 in the API alongside a prompting guide that explicitly warns against treating it as a drop-in replacement for gpt-5.2 or gpt-5.4. The guidance: start from a minimal prompt that preserves the product contract, then tune reasoning effort, verbosity, tool descriptions, and output format against representative examples, rather than carrying forward an older prompt stack.

One concrete UX recommendation stands out — for multi-step tasks, emit a short user-visible acknowledgement before tool calls so long thinking phases don’t feel like a hung process. Codex already does this in practice. OpenAI is also pushing automated migration via its openai-docs skill, with $openai-docs migrate this project to gpt-5.5 running an upgrade agent that even rewrites prompts to fit the new model.

The broader signal is that prompt portability across model generations is degrading. Teams with brittle, heavily tuned prompt stacks should expect rework on each major version bump, and OpenAI is now openly steering them toward a clean-slate workflow rather than incremental edits.