From 5bf008f213314b221bd3d7cde8211a941c6ffec9 Mon Sep 17 00:00:00 2001 From: Konstantine Kahadze Date: Thu, 9 Jul 2026 12:53:53 -0700 Subject: [PATCH] Update OpenAI Docs skill for GPT-5.6 --- skills/.curated/openai-docs/SKILL.md | 41 +- .../openai-docs/references/latest-model.md | 15 +- .../openai-docs/references/prompting-guide.md | 373 ++++++++------- .../openai-docs/references/upgrade-guide.md | 187 +------- .../references/upgrading-to-gpt-5p6-sol.md | 448 ++++++++++++++++++ .../scripts/resolve-latest-model-info | 31 ++ ...-info.js => resolve-latest-model-info.cjs} | 30 +- skills/.system/openai-docs/SKILL.md | 43 +- .../openai-docs/references/latest-model.md | 18 +- .../openai-docs/references/prompting-guide.md | 373 ++++++++------- .../openai-docs/references/upgrade-guide.md | 187 +------- .../references/upgrading-to-gpt-5p6-sol.md | 448 ++++++++++++++++++ .../scripts/resolve-latest-model-info | 31 ++ ...-info.js => resolve-latest-model-info.cjs} | 30 +- 14 files changed, 1522 insertions(+), 733 deletions(-) create mode 100644 skills/.curated/openai-docs/references/upgrading-to-gpt-5p6-sol.md create mode 100755 skills/.curated/openai-docs/scripts/resolve-latest-model-info rename skills/.curated/openai-docs/scripts/{resolve-latest-model-info.js => resolve-latest-model-info.cjs} (82%) mode change 100755 => 100644 create mode 100644 skills/.system/openai-docs/references/upgrading-to-gpt-5p6-sol.md create mode 100755 skills/.system/openai-docs/scripts/resolve-latest-model-info rename skills/.system/openai-docs/scripts/{resolve-latest-model-info.js => resolve-latest-model-info.cjs} (82%) mode change 100755 => 100644 diff --git a/skills/.curated/openai-docs/SKILL.md b/skills/.curated/openai-docs/SKILL.md index ec6a2b0..784cc8d 100644 --- a/skills/.curated/openai-docs/SKILL.md +++ b/skills/.curated/openai-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: "openai-docs" -description: "Use when the user asks how to build with OpenAI products or APIs, asks about Codex itself or choosing Codex surfaces, needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; use OpenAI docs MCP tools for non-Codex docs questions, use the Codex manual helper first for broad Codex self-knowledge, and restrict fallback browsing to official OpenAI domains." +description: "Use when the user asks how to build with OpenAI products or APIs, asks about Codex itself or choosing Codex surfaces, needs up-to-date official documentation with citations, help choosing the latest model for a use case, latest/current/default-model prompting guidance, or model upgrade and prompt-upgrade guidance; use OpenAI docs MCP tools for non-Codex docs questions, use the Codex manual helper first for broad Codex self-knowledge, and restrict fallback browsing to official OpenAI domains." --- @@ -8,19 +8,28 @@ description: "Use when the user asks how to build with OpenAI products or APIs, Provide authoritative, current guidance from OpenAI developer docs using the developers.openai.com MCP server. "Docs MCP" means `mcp__openaiDeveloperDocs__search_openai_docs` and `mcp__openaiDeveloperDocs__fetch_openai_doc`; for API reference, schema, parameter, or required-field questions, also use `mcp__openaiDeveloperDocs__get_openapi_spec` when available. Official-domain web search is fallback after those tools are unavailable or unhelpful. Broad Codex questions use the manual helper before Docs MCP. This skill also owns model selection, API model migration, and prompt-upgrade guidance. -## Workflow Configuration +## First action for latest-model changes -### Source Priority +Before reading memory, inspecting the repo, fetching docs, or checking API credentials, classify the request: + +- **Latest/current prompting guidance, or change requested + latest/current/newest/recommended/default/flagship/unspecified target:** immediately execute `/scripts/resolve-latest-model-info` and inspect its JSON output. This includes asking how to prompt the latest model, changing prompts, a model picker, model references, an SDK integration, replacing an older named model with "the current model", or asking "which model should I migrate/upgrade to?". Do not directly fetch `latest-model.md` for this branch. +- **Pure model-selection question only, with no prompting guidance or requested change:** directly fetch `https://developers.openai.com/api/docs/guides/latest-model.md`; do not run the resolver. +- **Change requested + explicit target model:** preserve that target; do not run the latest-model resolver. For an explicit GPT-5.6 Sol or GPT-5.6-family migration, fetch the live GPT-5.6 model-guidance page and read `references/upgrading-to-gpt-5p6-sol.md` for skill-specific migration judgment. +- **Prompting or migration guidance for an explicitly named GPT-5-family model:** fetch `https://developers.openai.com/api/docs/guides/model-guidance?model=` through Docs MCP and extract the relevant migration section or the `## Prompting Best Practices` section through the next H2 heading. Do not substitute latest-model guidance. + +For the resolver branch, do not suppress or redirect its stdout. Success requires JSON containing `model`, `migrationGuideUrl`, and `promptingGuideUrl`; if the command exits without all three fields, run it once more before any fallback. + +## Source Priority - For Codex self-knowledge, use the Codex source route below; it owns when to use the manual helper, Docs MCP, or bounded uncertainty. - For non-Codex OpenAI docs questions, use `mcp__openaiDeveloperDocs__search_openai_docs` to find the most relevant doc pages. - For non-Codex OpenAI docs questions, fetch the relevant page with `mcp__openaiDeveloperDocs__fetch_openai_doc` before answering. If search is noisy, run a narrower Docs MCP search; when any plausible official OpenAI docs URL is known or found, try fetching that URL through Docs MCP before relying on web-search content. - For API reference, schema, parameter, or required-field questions, use `mcp__openaiDeveloperDocs__get_openapi_spec` when available to verify the API shape alongside the relevant guide or reference page. - Use `mcp__openaiDeveloperDocs__list_openai_docs` only when you need to browse or discover non-Codex pages without a clear query. -- For model-selection, "latest model", or default-model questions, fetch `https://developers.openai.com/api/docs/guides/latest-model.md` first. If that is unavailable, load `references/latest-model.md`. -- For model upgrades or prompt upgrades, run `node scripts/resolve-latest-model-info.js` only when the target is latest/current/default or otherwise unspecified; otherwise preserve the explicitly requested target. +- For latest/current prompting guidance, model upgrades, or prompt upgrades, apply the first-action classifier above. Run /scripts/resolve-latest-model-info rather than the implementation file. When `load_workspace_dependencies` is available, you may set `NODE` to its returned Node.js executable before running the wrapper, but do not depend on that tool being available or remembered. The wrapper uses `$NODE` when supplied, then PATH and bundled/system fallbacks. If it reports no usable runtime, call `load_workspace_dependencies` when available, set `NODE` to the returned Node.js executable, and retry the wrapper once. +- For docs-only model-selection questions that do not ask to change an app, project, repo, model configuration, or prompts, fetch `https://developers.openai.com/api/docs/guides/latest-model.md` first. If that is unavailable, load `references/latest-model.md`. - Preserve explicit target requests: if the user names a target model like "migrate to GPT-5.4", keep that requested target even if `latest-model.md` names a newer model. Mention newer guidance only as optional. -- If current remote guidance is needed, fetch both the returned migration and prompting guide URLs directly. If direct fetch fails, use MCP/search fallback; if that also fails, use bundled fallback references and disclose the fallback. +- If current remote guidance is needed, treat the returned migration and prompting guide URLs as opaque and fetch those exact URLs directly. Do not derive, substitute, or append a model query to them. If a prompting guide URL resolves to a combined model-guidance page, extract only the `## Prompting Best Practices` section through the next H2 heading. If a fetched guide contains only a title or no substantive body, retry the exact markdown URL through MCP/search fallback; if that also fails, use bundled fallback references and disclose the fallback. ## OpenAI product snapshots @@ -118,17 +127,16 @@ If MCP tools fail or no OpenAI docs resources are available: 1. Clarify whether the request is general docs lookup, model selection, a model-string upgrade, prompt-upgrade guidance, or broader API/provider migration. 2. For Codex self-knowledge requests, follow the Codex self-knowledge source procedure above. 3. For model-selection or upgrade requests, prefer current remote docs over bundled references when the user asks for latest/current/default guidance. - - Fetch `https://developers.openai.com/api/docs/guides/latest-model.md`. - - Find the latest model ID and explicit migration or prompt-guidance links. - - Prefer explicit links from the latest-model page over derived URLs. + - For docs-only model-selection questions, fetch `https://developers.openai.com/api/docs/guides/latest-model.md`, find the latest model ID and explicit migration or prompt-guidance links, and prefer explicit links over derived URLs. - For explicit named-model requests, preserve the requested model target. Mention newer remote guidance only as optional. - - For dynamic latest/current/default upgrades, run `node scripts/resolve-latest-model-info.js`, then fetch both returned guide URLs directly when possible. - - If direct guide fetch fails, use the developer-docs MCP tools or official OpenAI-domain search to find the same guide content. + - For latest/current/default prompting guidance or dynamic upgrades, run /scripts/resolve-latest-model-info as the first docs operation before any direct latest-model.md fetch or API-key credential gate, then fetch both returned guide URLs directly when possible. + - Fetch returned guide URLs exactly; do not derive or substitute model-specific URLs. + - If a direct guide fetch fails or returns only a title, use the developer-docs MCP tools or official OpenAI-domain search to find the same guide content. - If remote docs are unavailable, use bundled fallback references and say that fallback guidance was used. -4. For model upgrades, keep changes narrow: update active OpenAI API model defaults and directly related prompts only when safe. -5. Leave historical docs, examples, eval baselines, fixtures, provider comparisons, provider registries, pricing tables, alias defaults, low-cost fallback paths, and ambiguous older model usage unchanged unless the user explicitly asks to upgrade them. +4. For model upgrades, keep changes behavior-preserving and scoped: update active OpenAI API model defaults, directly related prompts, and the registries, routing, pricing, capability, or picker surfaces that the user actually placed in scope. +5. Leave historical docs, examples, eval baselines, fixtures, provider comparisons, intentionally pinned fallbacks, and ambiguous older model usage unchanged unless the user explicitly asks to upgrade them. Do not collapse a multi-model router or picker into one flagship model; preserve the existing cost, latency, and quality roles. 6. Keep SDK, tooling, IDE, plugin, shell, auth, and provider-environment migrations out of a model-and-prompt upgrade unless the user explicitly asks for them. -7. If an upgrade needs API-surface changes, schema rewiring, tool-handler changes, or implementation work beyond a literal model-string replacement and prompt edits, report it as blocked or confirmation-needed. +7. If a safe upgrade needs API-surface changes, schema rewiring, tool-handler changes, or broader implementation work, classify it explicitly. Make those changes when implementation is within the user's requested scope; otherwise report the exact blocker or confirmation needed instead of silently changing behavior. 8. For general docs lookup, start with a compact, title-like search query of 2-6 essential terms. Do not turn the full user question into a keyword list. Fetch the best page and exact section needed, and answer with concise citations. ## Reference map @@ -139,8 +147,9 @@ Read only what you need: - `scripts/fetch-codex-manual.mjs` -> current Codex manual fetch, verification, local temp cache, and outline generation. - `https://developers.openai.com/codex/codex-manual.md` -> current Codex self-knowledge synthesis, including setup, customization, skills, plugins, MCP, hooks, `AGENTS.md`, automations, and surface behavior; normally access it through the helper path and targeted file reads when temp caching is available. - `references/latest-model.md` -> bundled fallback for model-selection and "best/latest/current model" questions. -- `references/upgrade-guide.md` -> bundled fallback for model upgrade and upgrade-planning requests. -- `references/prompting-guide.md` -> bundled fallback for prompt rewrites and prompt-behavior upgrades. +- `references/upgrade-guide.md` -> bundled routing fallback for model upgrade and upgrade-planning requests. +- `references/upgrading-to-gpt-5p6-sol.md` -> GPT-5.6 Sol/family migration judgment, compatibility gates, optional feature boundaries, and validation. +- `references/prompting-guide.md` -> bundled GPT-5.6 prompting fallback plus the live Prompting Best Practices extraction contract. ## Quality rules diff --git a/skills/.curated/openai-docs/references/latest-model.md b/skills/.curated/openai-docs/references/latest-model.md index a1ffbfb..b3b173d 100644 --- a/skills/.curated/openai-docs/references/latest-model.md +++ b/skills/.curated/openai-docs/references/latest-model.md @@ -6,12 +6,14 @@ This file is a curated helper. Every recommendation here must be verified agains | Model ID | Use for | | --- | --- | -| `gpt-5.5` | Latest/default text and reasoning model for most new apps, including coding and tool-heavy workflows | -| `gpt-5.5-pro` | Maximum reasoning or quality when latency and cost matter less | -| `gpt-5.4` | Previous default text and reasoning model; use for existing GPT-5.4 integrations | -| `gpt-5.4-mini` | Lower-cost testing and lighter production workflows | -| `gpt-5.4-nano` | High-throughput simple tasks and classification | -| `gpt-5.5` | Explicit no-reasoning text path via `reasoning.effort: none` | +| `gpt-5.6` | Latest/default GPT-5.6 alias; routes to Sol | +| `gpt-5.6-sol` | Flagship GPT-5.6 tier for hardest quality-first, coding, and reasoning workflows | +| `gpt-5.6-terra` | Mini-like GPT-5.6 tier for balanced cost, latency, and quality | +| `gpt-5.6-luna` | Nano-like GPT-5.6 tier for high-throughput, simple, or strict-latency tasks | +| `gpt-5.5` | Previous default text and reasoning model; use for existing GPT-5.5 integrations | +| `gpt-5.4` | Older default text and reasoning model; use for existing GPT-5.4 integrations | +| `gpt-5.4-mini` | Older lower-cost testing and lighter production workflows | +| `gpt-5.4-nano` | Older high-throughput simple tasks and classification | | `gpt-4.1-mini` | Cheaper no-reasoning text | | `gpt-4.1-nano` | Fastest and cheapest no-reasoning text | | `gpt-5.3-codex` | Agentic coding, code editing, and tool-heavy coding workflows | @@ -33,5 +35,6 @@ This file is a curated helper. Every recommendation here must be verified agains ## Maintenance notes +- GPT-5.6 Pro is a Responses reasoning mode on the base model, not a separate `gpt-5.6-pro` slug. Verify the live model guide before recommending its request shape. - This file will drift unless it is periodically re-verified against current OpenAI docs. - If this file conflicts with current docs, the docs win. diff --git a/skills/.curated/openai-docs/references/prompting-guide.md b/skills/.curated/openai-docs/references/prompting-guide.md index 0d9273c..a9d407c 100644 --- a/skills/.curated/openai-docs/references/prompting-guide.md +++ b/skills/.curated/openai-docs/references/prompting-guide.md @@ -1,244 +1,287 @@ -GPT-5.5 works best when prompts define the outcome and leave room for the model to choose an efficient solution path. Compared with earlier models, you can often use shorter, more outcome-oriented prompts: describe what good looks like, what constraints matter, what evidence is available, and what the final answer should contain. +## Retrieve the live GPT-5.6 prompting guidance -Avoid carrying over every instruction from an older prompt stack. Legacy prompts often over-specify the process because earlier models needed more help staying on track. With GPT-5.5, that can add noise, narrow the model's search space, or lead to overly mechanical answers. +Use the OpenAI Docs MCP to fetch the live GPT-5.6 prompting guidance from: -For more detail on GPT-5.5 behavior changes, start with the [Using GPT-5.5 guide](/api/docs/guides/latest-model). This guide focuses on prompt changes that follow from those behavior changes. +https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6#prompting-best-practices -The patterns here are starting points. Adapt them to your product surface, tools, evals, and user experience goals. +Read only the `## Prompting Best Practices` section, stopping at the next H2 heading. The URL anchor points to the section visually, but the Docs MCP may return the full page, so explicitly extract only that section. -## Personality and behavior +Treat the live section as the canonical model-specific prompting guidance. Use the local guidance below only for skill-specific migration judgment: deciding what to preserve, remove, rewrite, or test when adapting an existing prompt stack to GPT-5.6. -GPT-5.5's default style is efficient, direct, and task-oriented. This is useful for production systems: responses stay focused, behavior is easier to steer, and the model avoids unnecessary conversational padding. +## Skill-specific migration judgment -For customer-facing assistants, support workflows, coaching experiences, and other conversational products, define both personality and collaboration style. +GPT-5.6 works best when prompts define the outcome, important constraints, available evidence, and completion bar, then leave room for the model to choose an efficient path. Compared with earlier GPT-5 models, many applications can use shorter prompts and smaller tool sets without losing quality. -- **Personality** controls how the assistant sounds: tone, warmth, directness, formality, humor, empathy, and level of polish. -- **Collaboration style** controls how the assistant works: when it asks questions, when it makes assumptions, how proactive it should be, how much context it gives, when it checks work, and how it handles uncertainty or risk. +Do not carry over every instruction from an older prompt stack. Legacy prompts often repeat rules, prescribe unnecessary steps, expose irrelevant tools, or include examples that no longer change behavior. With GPT-5.6, this can encourage extra exploration, repeated validation, and larger accumulated context. -Keep both short. Personality instructions should shape the user experience. Collaboration instructions should shape task behavior. Neither should replace clear goals, success criteria, tool rules, or stopping conditions. +Start with the smallest prompt and tool set that passes your evals. Add an instruction, example, or tool only when it fixes a measured failure mode. -Example personality block for a steady task-focused assistant: +## Simplify prompts first -```text -# Personality -You are a capable collaborator: approachable, steady, and direct. Assume the user is competent and acting in good faith, and respond with patience, respect, and practical helpfulness. +When migrating an existing prompt, remove redundant scaffolding before adding new GPT-5.6-specific instructions. -Prefer making progress over stopping for clarification when the request is already clear enough to attempt. Use context and reasonable assumptions to move forward. Ask for clarification only when the missing information would materially change the answer or create meaningful risk, and keep any question narrow. +Trim: -Stay concise without becoming curt. Give enough context for the user to understand and trust the answer, then stop. Use examples, comparisons, or simple analogies when they make the point easier to grasp. When correcting the user or disagreeing, be candid but constructive. When an error is pointed out, acknowledge it plainly and focus on fixing it. +- repeated statements of the same rule; +- generic “be thorough,” “be concise,” or “think step by step” language; +- examples that do not change behavior; +- process instructions for behavior the model already performs reliably; +- tools and tool descriptions unrelated to the task. -Match the user's tone within professional bounds. Avoid emojis and profanity by default, unless the user explicitly asks for that style or has clearly established it as appropriate for the conversation. -``` +Keep: -Example personality block for an expressive collaborative assistant: +- the user-visible outcome; +- success criteria and stopping conditions; +- safety, business, evidence, and permission constraints; +- tool-routing rules when the correct route is not obvious; +- required output shape and validation requirements. -```text -# Personality -Adopt a vivid conversational presence: intelligent, curious, playful when appropriate, and attentive to the user's thinking. Ask good questions when the problem is blurry, then become decisive once there is enough context. - -Be warm, collaborative, and polished. Conversation should feel easy and alive, but not chatty for its own sake. Offer a real point of view rather than merely mirroring the user, while staying responsive to their goals and constraints. - -Be thoughtful and grounded when the task calls for synthesis or advice. State a clear recommendation when you have enough context, explain important tradeoffs, and name uncertainty without becoming evasive. -``` - -For more expressive products, add warmth, curiosity, humor, or point of view explicitly, but keep the block short. Use personality to shape the experience, not to compensate for unclear goals or missing task instructions. - -## Improve time to first visible token with a preamble - -In streaming applications, users notice how long it takes before the first visible response appears. GPT-5.5 may spend time reasoning, planning, or preparing tool calls before emitting visible text. - -For longer or tool-heavy tasks, prompt the model to start with a short preamble: a brief visible update that acknowledges the request and states the first step. This can improve perceived responsiveness without changing the underlying task. - -Use this pattern when the task may take more than one step, require tool calls, or involve a long-running agent workflow. - -```text -Before any tool calls for a multi-step task, send a short user-visible update that acknowledges the request and states the first step. Keep it to one or two sentences. -``` - -For coding agents that expose separate message phases, you can be more explicit: - -```text -You must always start with an intermediary update before any content in the analysis channel if the task will require calling tools. The user update should acknowledge the request and explain your first step. -``` +Review the remaining instructions for contradictions. GPT-5-class models follow prompt contracts closely, so conflicting rules can create more instability than missing detail. ## Outcome-first prompts and stopping conditions -GPT-5.5 is strongest when the prompt defines the target outcome, success criteria, constraints, and available context, then lets the model choose the path. +Describe the destination rather than prescribing every step. GPT-5.6 can usually choose an efficient search, tool, or reasoning path when the prompt states what good looks like. -For many tasks, describe the destination rather than every step. This gives the model room to choose the right search, tool, or reasoning strategy for the task. +Prefer: -Prefer this: + Resolve the customer's issue end to end. -```text -Resolve the customer's issue end to end. + Success means: + - make the eligibility decision from available policy and account evidence + - complete any allowed action before responding + - return completed_actions, customer_message, and blockers + - if required evidence is missing, ask for the smallest missing field -Success means: -- the eligibility decision is made from the available policy and account data -- any allowed action is completed before responding -- the final answer includes completed_actions, customer_message, and blockers -- if evidence is missing, ask for the smallest missing field -``` +Avoid unnecessary absolute rules. Use ALWAYS, NEVER, must, and only for true invariants such as safety rules, required fields, or actions that should never happen. For judgment calls, such as when to search, ask, use a tool, or keep iterating, prefer decision rules. -**Avoid unnecessary absolute rules.** Older prompts often use strict instructions like `ALWAYS`, `NEVER`, `must`, and `only` to control model behavior. Use those words for true invariants, such as safety rules, required output fields, or actions that should never happen. For judgment calls, such as when to search, ask for clarification, use a tool, or keep iterating, prefer decision rules instead. +Preserve explicit user values. When the correct value is implicit, provide decision criteria and let the model reason from context or schema. Avoid universal defaults, keyword maps, and broad semantic shortcuts. -Avoid this style of instruction unless every step is truly required: +Add stopping conditions: -```text -First inspect A, then inspect B, then compare every field, then think through -all possible exceptions, then decide which tool to call, then call the tool, -then explain the entire process to the user. -``` + Resolve the request in the fewest useful tool loops, but do not let loop + minimization outrank correctness, required evidence, calculations, or + required citations. -Add explicit stopping conditions: + After each result, ask whether the core request can now be answered with + useful evidence. If yes, answer. If required evidence is still missing, + name the missing fact and use the smallest useful fallback. -```text -Resolve the user query in the fewest useful tool loops, but do not let loop minimization outrank correctness, accessible fallback evidence, calculations, or required citation tags for factual claims. +## Personality, collaboration, and response length -After each result, ask: "Can I answer the user's core request now with useful evidence and citations for the factual claims?" If yes, answer. -``` +GPT-5.6 is efficient, direct, and more compressed than recent models. For customer-facing assistants and collaborative products, define both personality and collaboration style. -Define missing-evidence behavior: +- Personality controls tone, warmth, directness, formality, humor, empathy, and polish. +- Collaboration style controls when the model asks questions, makes assumptions, takes initiative, explains tradeoffs, checks work, and handles uncertainty. -```text -Use the minimum evidence sufficient to answer correctly, cite it precisely, then stop. -``` +Keep both short. Personality should shape the user experience; collaboration instructions should shape task behavior. Neither should replace clear goals, success criteria, tool rules, or stopping conditions. -## Formatting +Use concrete writing controls: -GPT-5.5 is highly steerable on output format and structure. Use that control when it improves comprehension or product fit. + Lead with the conclusion. Include the evidence needed to support it, any + material caveat, and the next action. Keep all required facts, decisions, + caveats, and next steps. Trim introductions, repetition, generic reassurance, + and optional background first. -Set `text.verbosity`, describe the expected output shape, and reserve heavier structure for cases where it improves comprehension or your product UI needs a stable artifact. The API default for `text.verbosity` is `medium`; use `low` when you prefer shorter, more concise responses. +Avoid generic “be brief,” “keep it short,” or “use minimal text” instructions. GPT-5.6 is already biased toward compression, and generic brevity can make it omit required evidence or parts of an artifact. -Plain conversational formatting: +For customer-facing tone, prefer concrete guidance: -```text -Let formatting serve comprehension. Use plain paragraphs as the default format for normal conversation, explanations, reports, documentation, and technical writeups. Keep the presentation clean and readable without making the structure feel heavier than the content. + Be direct and tactful. Acknowledge friction specifically when relevant. + Avoid canned reassurance and unnecessary sign-offs. -Use headers, bold text, bullets, and numbered lists sparingly. Reach for them when the user requests them, when the answer needs clear comparison or ranking, or when the information would be harder to scan as prose. Otherwise, favor short paragraphs and natural transitions. +Avoid blanket language rules such as “always respond in the user's language” unless that is truly the product requirement. Specify the intended output language and when it should change. -Respect formatting preferences from the user. If they ask for a terse answer, minimal formatting, no bullets, no headers, or a specific structure, follow that preference unless there is a strong reason not to. -``` +For editing, rewriting, summaries, and customer-facing drafts, tell the model what to preserve: -Add explicit audience and length guidance: + Preserve the requested artifact, length, structure, genre, and factual claims + first. Improve clarity, flow, and correctness without adding new claims, + sections, or a more promotional tone unless requested. -```text -Write for a senior business audience. Keep the answer under 400 words. Use short paragraphs and only include bullets when they improve scannability. Prioritize the conclusion first, then the reasoning, then caveats. -``` +## Autonomy and permissions -For editing, rewriting, summaries, or customer-facing messages, tell the model what to preserve before asking it to improve style. This pattern is useful when you want polish without expansion. +GPT-5.6 can be proactive and persistent. Define which level of action each request authorizes. -```text -Preserve the requested artifact, length, structure, and genre first. Quietly improve clarity, flow, and correctness. Do not add new claims, extra sections, or a more promotional tone unless explicitly requested. -``` + For requests to answer, explain, review, diagnose, or plan, inspect the + relevant materials and report the result. Do not implement changes unless + the request also asks for them. + + For requests to change, build, or fix, make the requested in-scope local + changes and run relevant non-destructive validation without asking first. + + Require confirmation for external writes, destructive actions, purchases, + or a material expansion of scope. + +Specify which local actions are safe without approval, such as reading files, inspecting logs, searching, editing in-scope code, and running non-destructive tests. + +Avoid repeating “ask first” throughout the prompt. Repetition can cause unnecessary permission checks even for safe, expected actions. + +For long-running work, define the current layer of work. Distinguish research, design, implementation, review, and external coordination so the model does not silently move from one layer to another. + +## Tool routing + +Expose only task-relevant tools. Tool descriptions should state what the tool does, when to use it, important return fields, and error behavior. + +When correctness depends on prerequisite retrieval or lookup, say so: + + Before taking an action, resolve required discovery, retrieval, and + validation steps. Do not skip a prerequisite because the intended final + state seems obvious. + +When several reads are independent, parallelize them. When one result determines the next action, keep the work sequential. After parallel retrieval, synthesize before acting. + +If a tool returns empty, partial, or suspiciously narrow results, try one or two meaningful fallbacks before concluding that no result exists. + +## Programmatic Tool Calling + +Programmatic Tool Calling is useful when code can reduce large, structured intermediate results before they return to model context. + +Use it for: + +- filtering, joining, sorting, ranking, deduplication, and aggregation; +- batching across many similar records; +- repeated deterministic validation; +- large structured results that can be reduced to a compact schema. + +Prefer direct tool calls when: + +- one call is sufficient; +- intermediate outputs are already small; +- each result may change the next decision; +- an action requires approval; +- the final answer must preserve citations or native artifacts; +- the workflow requires semantic judgment between calls. + +Do not rely on generic instructions such as “use Programmatic Tool Calling efficiently.” State the bounded stage, eligible tools, output schema, retry limit, stop condition, and handoff back to direct model judgment. + + Use Programmatic Tool Calling only for the bounded record-reduction stage. + Call only the documented read-only tools. Filter and deduplicate the + intermediate results, then emit exactly the required compact schema with + evidence fields. Retry transient failures at most twice. Use direct tool + calls for approval, semantic judgment, citations, and final validation. + +Evaluate the final user-visible answer, not only the program result. Lower tokens, latency, calls, or turns are improvements only when the final answer still meets the required quality bar. ## Grounding, citations, and retrieval budgets -For grounded answers, citation behavior should be part of the prompt. Define what needs support, what counts as enough evidence, and how the model should behave when evidence is missing. Absence of evidence shouldn't automatically become a factual "no." For more details and examples, see the [citation formatting guide](/api/docs/guides/citation-formatting). +For grounded answers, citation behavior should be part of the prompt. Define what needs support, what counts as enough evidence, and how to behave when evidence is missing. Absence of evidence should not automatically become a factual “no.” -### Add an explicit retrieval budget + For ordinary Q&A, start with one broad search using short, discriminative + keywords. If the top results contain enough support for the core request, + answer from those results. -Retrieval budgets are stopping rules for search. They tell the model when enough evidence is enough. + Make another retrieval call only when a required fact, owner, date, ID, or + source is missing; the user asked for exhaustive coverage or comparison; a + specific artifact must be read; or an important claim would otherwise be + unsupported. -```text -For ordinary Q&A, start with one broad search using short, discriminative keywords. If the top results contain enough citable support for the core request, answer from those results instead of searching again. + Do not search again only to improve phrasing, add examples, or support + nonessential detail. -Make another retrieval call only when: -- The top results do not answer the core question. -- A required fact, parameter, owner, date, ID, or source is missing. -- The user asked for exhaustive coverage, a comparison, or a comprehensive list. -- A specific document, URL, email, meeting, record, or code artifact must be read. -- The answer would otherwise contain an important unsupported factual claim. +For research and synthesis: -Do not search again to improve phrasing, add examples, cite nonessential details, or support wording that can safely be made more generic. -``` +- cite only retrieved sources; +- attach citations to the claims they support; +- label inference separately from directly supported facts; +- state conflicts between sources; +- narrow the answer or report missing evidence instead of guessing. -## Creative drafting guardrails +For creative drafting, distinguish source-backed facts from creative wording. Do not invent names, metrics, dates, roadmap status, customer outcomes, or product capabilities to make a draft sound stronger. -For drafting tasks, tell the model which claims must come from sources and which parts may be creatively written. This is especially important for slides, launch copy, customer summaries, talk tracks, leadership blurbs, and narrative framing. +## Long-running workflows and state -```text -For creative or generative requests such as slides, leadership blurbs, outbound copy, summaries for sharing, talk tracks, or narrative framing, distinguish source-backed facts from creative wording. +For multi-step or tool-heavy tasks, prompt for a short visible preamble before the first tool call, then sparse outcome-based updates at major phase changes. Do not ask the model to narrate routine tool calls. -- Use retrieved or provided facts for concrete product, customer, metric, roadmap, date, capability, and competitive claims, and cite those claims. -- Do not invent specific names, first-party data claims, metrics, roadmap status, customer outcomes, or product capabilities to make the draft sound stronger. -- If there is little or no citable support, write a useful generic draft with placeholders or clearly labeled assumptions rather than unsupported specifics. -``` + Before tool calls for a multi-step task, send a one- or two-sentence + user-visible update that states the first step. During the task, update only + when a major phase begins or a finding changes the plan. Each update should + state one concrete outcome and the next step. -## Frontend engineering and visual taste +Preserve assistant phase values when replaying history so the model can distinguish commentary from the final answer. If using previous_response_id, prior assistant state is preserved automatically. If replaying history manually, preserve each original phase value unchanged. -For frontend work, refer to the [example instructions](/api/docs/guides/frontend-prompt) for practical ways to steer UI quality. They cover product and user context, design-system alignment, first-screen usability, familiar controls, expected states, responsive behavior, and common generated-UI defaults to avoid, such as generic heroes, nested cards, decorative gradients, visible instructional text, and broken layouts. +Compact after major milestones rather than every turn. Keep the prompt functionally consistent after compaction and treat compacted items as opaque state. -## Prompt the model to check its work +Persisted reasoning is useful when the objective, assumptions, and priorities remain stable across turns. Use current-turn behavior when earlier reasoning is no longer relevant. Do not treat persisted reasoning as an always-on optimization: stale reasoning can add tokens, increase latency, and anchor the model to an outdated approach. -Give GPT-5.5 access to tools that let it check outputs when validation is possible. +Prompt caching also affects prompt construction. Keep reusable prefixes stable and avoid unnecessary churn in large system prompts. Use explicit cache breakpoints only when they improve measured cache behavior and cost for the workload. -For coding agents, ask for concrete validation commands: +## Reasoning effort -```text -After making changes, run the most relevant validation available: -- targeted unit tests for changed behavior -- type checks or lint checks when applicable -- build checks for affected packages -- a minimal smoke test when full validation is too expensive +Treat reasoning effort as a last-mile tuning knob, not the first response to a weak result. -If validation cannot be run, explain why and describe the next best check. -``` +- Preserve the current GPT-5.5 or GPT-5.4 reasoning effort as the baseline. +- Test the same setting and one level lower on representative tasks. +- Use low for latency-sensitive work when it preserves quality. +- Use medium as a balanced starting point. +- Use high or xhigh only when evals show a meaningful gain. +- Reserve max for the hardest quality-first workloads; do not recommend it globally. -For visual artifacts, ask for inspection after rendering: +Before increasing reasoning effort, check whether the prompt is missing a success criterion, dependency rule, tool-routing rule, or verification loop. -```text -Render the artifact before finalizing. Inspect the rendered output for layout, clipping, spacing, missing content, and visual consistency. Revise until the rendered output matches the requirements. -``` +## Frontend and visual tasks -For engineering and planning tasks, make implementation plans traceable: +GPT-5.6 has stronger layout, visual hierarchy, and design judgment. Still provide product context, preserve the existing design system, and name the states and constraints that matter. -```text -For implementation plans, include: -- requirements and where each is addressed -- named resources, files, APIs, or systems involved -- state transitions or data flow where relevant -- validation commands or checks -- failure behavior -- privacy and security considerations -- open questions that materially affect implementation -``` +For incremental frontend changes: -## Phase parameter +- inspect and preserve existing design tokens, components, and patterns; +- do not add extra features or decorative UI unless requested; +- preserve responsive behavior and expected states; +- render and inspect the result before finalizing. -Starting with GPT-5.4, long-running or tool-heavy Responses workflows can use assistant-item `phase` values to distinguish intermediate updates from final answers. GPT-5.5 uses the same pattern. +For vision, computer use, localization, or OCR tasks where spatial precision matters, choose image detail intentionally. Use original detail for large, dense, or coordinate-sensitive images when the extra input cost and latency are justified. -If you use `previous_response_id`, the API preserves prior assistant state automatically. If your application manually replays assistant output items into the next request, preserve each original `phase` value and pass it back unchanged. This matters most when a response includes preambles, repeated tool calls, or a final answer after intermediate assistant updates. +## Check work before finishing -```text -If manually replaying assistant items: -- Preserve assistant `phase` values exactly. -- Use `phase: "commentary"` for intermediate user-visible updates. -- Use `phase: "final_answer"` for the completed answer. -- Do not add `phase` to user messages. -``` +Give GPT-5.6 access to tools that can validate the output, and state what validation matters. + +For coding: + + After making changes, run the most relevant validation available: + - targeted tests for changed behavior + - type checks or lint checks when applicable + - build checks for affected packages + - a minimal smoke test when full validation is too expensive + + If validation cannot be run, explain why and describe the next best check. + +For visual artifacts: + + Render the artifact before finalizing. Inspect layout, clipping, spacing, + missing content, and visual consistency. Revise until the rendered output + matches the requirements. + +For implementation plans, include requirements, named resources or files, state transitions or data flow, validation checks, failure behavior, privacy or security considerations, and open questions that materially affect implementation. ## Suggested prompt structure Use this structure as a starting point for complex prompts. Keep each section short. Add detail only where it changes behavior. -```text -Role: [1-2 sentences defining the model's function, context, and job] + Role: [the model's function and context] -# Personality -[tone, demeanor, and collaboration style] + Personality: [tone and collaboration style] -# Goal -[user-visible outcome] + Goal: [user-visible outcome] -# Success criteria -[what must be true before the final answer] + Success criteria: [what must be true before the final answer] -# Constraints -[policy, safety, business, evidence, and side-effect limits] + Constraints: [policy, safety, business, evidence, and side-effect limits] -# Output -[sections, length, and tone] + Tools: [which tools to use, when, and what not to use] -# Stop rules -[when to retry, fallback, abstain, ask, or stop] -``` + Output: [sections, length, format, and tone] + + Stop rules: [when to retry, fallback, abstain, ask, or stop] + +## Prompt migration workflow + +When moving an existing application to GPT-5.6: + +1. Switch the model and preserve the current reasoning effort. +2. Run representative evals before changing the prompt. +3. Remove obsolete scaffolding, repeated instructions, and irrelevant tools. +4. Add only the smallest targeted instruction that fixes a measured regression. +5. Re-run evals after each prompt or reasoning change. + +Do not rewrite a working prompt stack all at once. Otherwise you cannot tell whether a behavior change came from the model, reasoning setting, prompt, tool set, or runtime. + +When a prompt regresses, debug it with a small set of real traces. Identify the failure mode, find the instruction or contradiction that likely caused it, make a surgical edit, and rerun the same cases. diff --git a/skills/.curated/openai-docs/references/upgrade-guide.md b/skills/.curated/openai-docs/references/upgrade-guide.md index b29f137..8134bc6 100644 --- a/skills/.curated/openai-docs/references/upgrade-guide.md +++ b/skills/.curated/openai-docs/references/upgrade-guide.md @@ -1,181 +1,22 @@ -# Upgrading to GPT-5.5 +# Model upgrade guidance -Use this guide when the user explicitly asks to upgrade an existing integration to GPT-5.5. Pair it with current OpenAI docs lookups. The default target string is `gpt-5.5`. +Use this file only as a bundled routing fallback when the live migration guide cannot be fetched. -## Freshness check +For latest, current, default, or unspecified-model upgrades: -Before applying this bundled guide for a latest/current/default model upgrade, run `node scripts/resolve-latest-model-info.js` from the OpenAI Docs skill directory. +1. Run `scripts/resolve-latest-model-info`. +2. Fetch the returned `migrationGuideUrl` and `promptingGuideUrl` exactly. +3. Treat the live guides as canonical. +4. If remote retrieval fails, disclose that bundled fallback guidance is being used. -- If the command returns `modelSlug: "gpt-5p5"`, continue with this bundled guide and use `references/prompting-guide.md` when prompt updates are needed. -- If the command returns a different `modelSlug`, fetch both the returned `migrationGuideUrl` and `promptingGuideUrl` and use them as the current source of truth instead of the bundled references. -- If the command fails, metadata is missing, or either remote guide cannot be fetched, continue with bundled fallback references and say the remote freshness check was unavailable. -- If the user explicitly named a target model, preserve that target and use current docs only to check compatibility or caveats. +For an explicit GPT-5.6 Sol or GPT-5.6-family migration: -## Upgrade posture +1. Preserve the user's explicit target; do not run the latest-model resolver. +2. Fetch the live GPT-5.6 model guidance: -Upgrade with the narrowest safe change set: + https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6 -- replace the model string first -- update only the prompts that are directly tied to that model usage -- do not automatically upgrade older or ambiguous model usages that may be intentionally pinned, such as historical docs, examples, tests, eval baselines, comparison code, or low-cost fallback/routing paths. Unless the user explicitly asks to upgrade all model usage, leave those sites unchanged and list them as confirmation-needed -- prefer prompt-only upgrades when possible -- if the upgrade would require API-surface changes, parameter rewrites, tool rewiring, provider migration, or broader code edits, mark it as blocked instead of stretching the scope +3. Read `references/upgrading-to-gpt-5p6-sol.md` for skill-specific migration judgment. +4. Read `references/prompting-guide.md` only when prompt changes are needed. -## Upgrade workflow - -1. Inventory current model usage. - - Search for model strings, client calls, and prompt-bearing files. - - Include inline prompts, prompt templates, YAML or JSON configs, Markdown docs, and saved prompts when they are clearly tied to a model usage site. -2. Pair each model usage with its prompt surface. - - Prefer the closest prompt surface first: inline system or developer text, then adjacent prompt files, then shared templates. - - If you cannot confidently tie a prompt to the model usage, say so instead of guessing. -3. Classify the source model family. - - Common buckets: GPT-5.4, GPT-5.3-Codex or GPT-5.2-Codex, earlier GPT-5.x, GPT-4o or GPT-4.1, reasoning models such as o1 or o3 or o4-mini, third-party model, or mixed and unclear. -4. Decide the upgrade class. - - `model string only` - - `model string + light prompt rewrite` - - `blocked without code changes` -5. Run the compatibility gate. - - Check whether the current integration can accept `gpt-5.5` without API-surface changes or implementation changes. - - Check whether structured outputs, tool schemas, function names, and downstream parsers can remain unchanged. - - For long-running Responses or tool-heavy agents, check whether `phase` is already preserved or round-tripped when the host replays assistant items or uses preambles. - - If compatibility depends on code changes, return `blocked`. - - If compatibility is unclear, return `unknown` rather than improvising. -6. Apply the upgrade when it is in scope. - - Default replacement string: `gpt-5.5`. - - Keep the intervention small and behavior-preserving. - - Start from the current reasoning effort when it is visible unless there is a measured reason to change it. - - For in-scope changes, update the model string and directly related prompts. - - For blocked or unknown changes, do not edit; report the blocker or uncertainty. -7. Summarize the result. - - `Current model usage` - - `Model-string updates` - - `Reasoning-effort handling` - - `Prompt updates` - - `Structured output and formatting assessment` - - `Tool-use assessment` when the flow uses tools, retrieval, or terminal actions - - `Phase assessment` when the flow is long-running, replayed, or tool-heavy - - `Compatibility check` - - `Validation performed` - -Output rule: - -- For each usage site, state the starting reasoning-effort recommendation. -- If the repo exposes the current reasoning setting, recommend preserving it first unless current OpenAI docs say otherwise. -- If the repo does not expose the current setting, recommend not adding one unless current OpenAI docs require it. - -## Upgrade outcomes - -### `model string only` - -Choose this when: - -- the source model is GPT-5.4 -- the existing prompts are already short, explicit, and task-bounded -- the workflow does not rely on strict output formats, tool-call behavior, batch completeness, or long-horizon execution that should be validated after the upgrade -- there are no obvious compatibility blockers - -Default action: - -- replace the model string with `gpt-5.5` -- preserve the current reasoning effort -- keep prompts unchanged -- validate behavior with existing tests, realistic spot checks, or an existing eval suite when one is already available - -### `model string + light prompt rewrite` - -Choose this when: - -- the task needs stronger completeness, citation discipline, verification, or dependency handling -- the upgraded model becomes too verbose, too dense, or hard to scan unless formatting is constrained -- the workflow has strict output shape requirements and lacks an explicit format contract, schema, or parser validation -- the workflow is research-heavy and needs stronger handling of sparse or empty retrieval results -- the workflow is coding-oriented, terminal-based, tool-heavy, or multi-agent, but the existing API surface and tool definitions can remain unchanged - -Default action: - -- replace the model string with `gpt-5.5` -- preserve the current reasoning effort for the first pass -- make only the smallest prompt edits needed for the observed workflow risk -- read the [GPT-5.5 prompting guide](/api/docs/guides/prompt-guidance?model=gpt-5.5) to choose the smallest prompt changes that recover or improve behavior -- avoid broad prompt cleanup unrelated to the upgrade -- for research workflows, add citation rules, retrieval budgets, missing-evidence behavior, and validation guidance from the prompting guide -- for dependency-aware or tool-heavy workflows, add prerequisite checks, missing-context handling, explicit tool budgets, stop conditions, and validation guidance -- for coding or terminal workflows, add repo-specific constraints, acceptance criteria, and concrete validation commands -- for multi-agent support or triage workflows, add task ownership, handoff, completeness, and stopping criteria -- for long-running Responses agents with preambles or multiple assistant messages, explicitly review whether `phase` is already handled; if adding or preserving `phase` would require code edits, mark the path as `blocked` -- do not classify a coding or tool-using Responses workflow as `blocked` just because the visible snippet is minimal; prefer `model string + light prompt rewrite` unless the repo clearly shows that a safe GPT-5.5 path would require host-side code changes - -### `blocked` - -Choose this when: - -- the upgrade appears to require API-surface changes -- the upgrade appears to require parameter rewrites or reasoning-setting changes that are not exposed outside implementation code -- the upgrade would require changing tool definitions, tool handler wiring, or schema contracts -- the user is asking for a tooling, IDE, plugin, shell, or environment migration rather than a model and prompt migration -- the integration depends on provider-specific APIs that do not map to the current OpenAI API surface without implementation work -- you cannot confidently identify the prompt surface tied to the model usage - -Default action: - -- do not improvise a broader upgrade -- report the blocker and explain that the fix is out of scope for this guide -- if useful, describe the smallest follow-up implementation task that would unblock the migration - -## Compatibility checklist - -Before applying or recommending a model-and-prompt-only upgrade, check: - -1. Can the current host accept the `gpt-5.5` model string without changing client code or API surface? -2. Are the related prompts identifiable and editable? -3. Does the host depend on behavior that likely needs API-surface changes, parameter rewrites, provider migration, or tool rewiring? -4. Would the likely fix be prompt-only, or would it need implementation changes? -5. Is the prompt surface close enough to the model usage that you can make a targeted change instead of a broad cleanup? -6. Do strict structured outputs, schemas, or downstream parsers still have an explicit contract? -7. For long-running Responses or tool-heavy agents, is `phase` already preserved if the host relies on preambles, replayed assistant items, or multiple assistant messages? -8. Are latency, token, or price assumptions validated by tests, realistic spot checks, or an existing eval suite rather than inferred from general model positioning? - -If item 1 is no, items 3 through 4 point to implementation work, or item 7 is no and the fix needs code changes, return `blocked`. - -If item 2 is no, return `unknown` unless the user can point to the prompt location. - -Important: - -- Existing use of tools, agents, or multiple usage sites is not by itself a blocker. -- If the current host can keep the same API surface and the same tool definitions, prefer `model string + light prompt rewrite` over `blocked`. -- Reserve `blocked` for cases that truly require implementation changes, not cases that only need stronger prompt steering. -- Do not claim token savings without task-level validation. - -## Scope boundaries - -This guide may: - -- update or recommend updated model strings -- update or recommend updated prompts -- inspect code and prompt files to understand where those changes belong -- inspect whether existing Responses flows already preserve `phase` -- flag compatibility blockers -- propose validation with existing tests, realistic spot checks, or existing eval suites - -This guide may not: - -- move Chat Completions code to Responses -- move Responses code to another API surface -- migrate SDKs, APIs, IDE configuration, shell hooks, plugins, or provider-specific tooling -- rewrite parameter shapes -- change tool definitions or tool-call handling -- change structured-output wiring -- add or retrofit `phase` handling in implementation code -- edit business logic, orchestration logic, SDK usage, IDE configuration, shell hooks, or plugin integration behavior except for model-string replacements and directly related prompt edits - -If a safe GPT-5.5 upgrade requires any of those changes, mark the path as blocked and out of scope. - -## Validation plan - -- Validate each upgraded usage site with existing tests, realistic spot checks, or an existing eval suite when one is already available. -- Compare against the current GPT-5.4 baseline when available. -- Check task success, retry count, tool-call count, total tokens, latency, output shape, and user-visible quality. -- For specialized workflows, validate the contract that matters most instead of judging only general output quality. -- If prompt edits were added, confirm each block is doing real work instead of adding noise. -- If the workflow has downstream impact, add a lightweight verification pass before finalization. +For another explicit model target, preserve that target and fetch its current official guidance. Do not reuse GPT-5.6-specific defaults, API shapes, or compatibility rules for a different model. diff --git a/skills/.curated/openai-docs/references/upgrading-to-gpt-5p6-sol.md b/skills/.curated/openai-docs/references/upgrading-to-gpt-5p6-sol.md new file mode 100644 index 0000000..4cff512 --- /dev/null +++ b/skills/.curated/openai-docs/references/upgrading-to-gpt-5p6-sol.md @@ -0,0 +1,448 @@ +# Upgrading to GPT-5.6 Sol + +Use this guide when the user asks to migrate an existing OpenAI API integration, repository, prompt stack, agent, model router, or model picker to GPT-5.6 Sol or the GPT-5.6 family. + +The default explicit target is `gpt-5.6-sol`. The alias `gpt-5.6` routes to Sol; use it only when the repository intentionally prefers family aliases. Do not treat every old model usage as a Sol candidate: GPT-5.6 is a family with different cost, latency, context, and quality roles. + +Before changing code, use the OpenAI Docs MCP to fetch the current live GPT-5.6 model guidance: + +https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6 + +For prompt changes, also read only the `## Prompting Best Practices` section from: + +https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6#prompting-best-practices + +Treat live docs as canonical for current model IDs, parameters, limits, pricing, and feature availability. This file supplies migration judgment: where to look, what can break, what to preserve, what not to adopt automatically, and how to validate the result. + +## Core principle + +Do not perform a blind model-string replacement. + +First preserve the behavior, latency class, cost class, reasoning level, endpoint contract, tool semantics, cache behavior, and output contract of each usage site. Then make the smallest safe migration. Adopt new GPT-5.6 capabilities only when they solve a measured problem or the user explicitly asks for them. + +A model upgrade alone does not authorize adding reasoning fields, changing request schemas, or rewriting tests. Only add explicit reasoning when the old effective behavior is established and omission would change behavior on GPT-5.6. + +The main 5.6 migration hazards are: + +- choosing Sol for workloads that were intentionally mini, nano, low-cost, or latency-sensitive; +- inheriting 5.6's default `medium` reasoning where the old effective effort was `none`; +- using Chat Completions with function tools without explicitly setting effective reasoning to `none`; +- losing prompt-cache hits when a stable prefix is followed by a changing suffix; +- increasing image or PDF input tokens because omitted or `auto` detail behaves differently; +- applying new cache, persisted-reasoning, Pro, Programmatic Tool Calling, or multi-agent fields to routes that do not support them; +- updating model strings but forgetting registries, allowlists, pricing metadata, capability flags, tests, and UI model pickers. + +## Migration posture + +Classify every usage site before editing: + +1. `simple Sol migration` + - One flagship model usage. + - Same endpoint and request shape can remain. + - Reasoning effort is explicit or its old effective value is known. + - No cache, vision, file, tool, or parser behavior needs implementation changes. +2. `tier-aware family migration` + - The repository exposes multiple model roles, model choices, fallbacks, routers, pricing data, or capability metadata. + - Map each role to Sol, Terra, or Luna instead of replacing everything with Sol. +3. `compatibility migration` + - The safe move requires parameter, endpoint, cache, state, tool-loop, or multimodal-detail changes. + - Make these changes only when implementation work is inside the user's requested scope. Otherwise report the exact blocker and smallest follow-up. +4. `prompt migration` + - The API shape can remain, but representative traces show a prompt-specific regression. + - Make a surgical prompt edit tied to that failure; do not rewrite a working prompt stack wholesale. + - When the task is to update prompting guidance, edit the directly tied prompt surface only. Do not modify runtime request code, model schemas, or tests unless the prompt change requires it. +5. `optional feature adoption` + - Pro mode, persisted reasoning, explicit caching, Programmatic Tool Calling, or multi-agent behavior is being added deliberately. + - Keep this separate from the baseline migration so its effect can be measured. +6. `leave unchanged` + - Historical examples, documentation about old models, snapshots, fixtures, eval baselines, comparison code, intentionally pinned fallbacks, unsupported providers, or ambiguous usages. + +When intent is unclear, prefer leaving a usage unchanged and list it for confirmation over silently changing its role. + +## Inventory before editing + +Search for more than literal model IDs. Inventory: + +- model strings, aliases, environment variables, CLI flags, config defaults, and deployment settings; +- SDK calls to Responses, Chat Completions, Batch, or provider adapters; +- reasoning settings, token budgets, sampling settings, and latency timeouts; +- function tools, hosted tools, structured outputs, response parsers, and replay logic; +- system, developer, user, and tool-description prompts tied to each usage; +- routers, fallbacks, model allowlists, enums, regexes, validation schemas, and capability maps; +- model picker UI, display labels, descriptions, context limits, pricing metadata, and provider catalogs; +- prompt-cache keys, retention options, stable-prefix construction, and cache metrics; +- image, PDF, file, OCR, and computer-use inputs; +- tests, fixtures, snapshots, evals, analytics labels, billing tables, and docs. + +When changing a default model, search every active default surface: runtime config, environment/config files, setup docs, tests, CLI defaults, and deployment examples. Update them together. + +For each usage site, record: + +- source model and why it appears to be used; +- endpoint and SDK/client surface; +- prompt surface; +- effective reasoning effort, including defaults; +- latency, cost, context, and quality role; +- tools, structured outputs, caching, state replay, and multimodal inputs; +- downstream parsers or user-visible contracts; +- migration class and validation plan. + +## Choose the target model by role + +Use this as a starting map, then validate against the repository's workload: + +| Existing role | Starting GPT-5.6 target | Reason | +| --- | --- | --- | +| Unsuffixed GPT-5 flagship, GPT-5.5, or GPT-5.4 flagship | `gpt-5.6-sol` | Sol is the flagship-equivalent tier. | +| Mini model, balanced lower-cost route, or medium-throughput worker | `gpt-5.6-terra` | Terra is the mini-like tier. | +| Nano model, classification, extraction, routing, high-volume, or strict-latency route | `gpt-5.6-luna` | Luna is the nano-like tier. | +| GPT-4.1 or GPT-4o latency-sensitive flow | Evaluate Luna and Terra first; use Sol only if quality requires it | A flagship replacement can change latency and cost materially. | +| Reasoning-heavy or hardest quality-first flow | Start with Sol at the old effective effort | Preserve the reasoning contract before tuning. | +| Old Pro usage | Sol plus `reasoning.mode: "pro"`, only if the user wants Pro behavior | GPT-5.6 Pro is a mode, not a separate model slug. | +| Router, fallback, or model picker | Add the family by role | Do not collapse a multi-model design into Sol. | +| Third-party or provider-specific model | Leave unchanged unless the user explicitly requests provider migration | Model-name similarity is not a safe mapping. | + +Important limits to check in live docs: + +- Sol and Terra have roughly 1.05M context and 128K maximum output. +- Luna has a smaller 400K context and 128K maximum output. +- Sol and Terra long-context requests above 272K input tokens can change pricing for the full request. + +Do not invent prices, limits, or capability flags. Fetch them from current docs before updating a registry or UI. + +For model pickers and registries, preserve existing model entries by default. Add GPT-5.6 Sol, Terra, and Luna as new options unless the user explicitly asks to replace or remove older models. Do not invent pricing, context limits, capabilities, or metadata unless confirmed from canonical docs. + +If using the `gpt-5.6` alias, record the returned `response.model` during validation. Do not assume an alias and an explicit Sol slug appear identically in dashboards, rate-limit configuration, analytics, or billing metadata. + +## Preserve effective reasoning before tuning + +GPT-5.6 supports `none`, `low`, `medium`, `high`, `xhigh`, and `max`. If omitted, GPT-5.6 defaults to `medium`. + +This is a behavioral migration hazard: + +- GPT-5.5 commonly defaulted to `medium`. +- GPT-5.4, mini, and nano usages commonly defaulted to `none`. +- A previously omitted setting can therefore become slower, more expensive, and incompatible with Chat Completions function tools after the model swap. + +For each usage: + +1. If effort is explicit, preserve it for the first 5.6 run when supported. +2. If effort is omitted and the old effective default is known, add it explicitly only when GPT-5.6's omitted default would change behavior. If both old and new omitted defaults are the same, keep it omitted. +3. If the old effective value is unknown, do not guess. Flag it and compare the old behavior with 5.6 at the likely baseline. +4. After the baseline passes, test the same setting and one lower on representative tasks. +5. Use `xhigh` or `max` only for hard quality-first workloads where evals show a meaningful gain. + +Do not globally recommend `max`. Before increasing effort, check whether the actual failure is a missing success criterion, dependency rule, tool-routing rule, state-replay bug, or validation loop. + +Use the field shape that belongs to the endpoint. + +Responses: + +```json +{ + "model": "gpt-5.6-sol", + "reasoning": { "effort": "none" } +} +``` + +Chat Completions: + +```json +{ + "model": "gpt-5.6-sol", + "reasoning_effort": "none" +} +``` + +## Chat Completions and function tools + +This is the most important endpoint-specific check. + +For GPT-5.6, function tools in Chat Completions are compatible only with effective reasoning `none`. Reasoning with tools should use the Responses API. + +Because GPT-5.6 defaults to `medium`, this combination is unsafe: + +```json +{ + "model": "gpt-5.6-luna", + "tools": [{ "type": "function", "function": { "...": "..." } }] +} +``` + +For a latency-sensitive Chat Completions flow that must keep function tools, explicitly preserve `none`: + +```json +{ + "model": "gpt-5.6-luna", + "reasoning_effort": "none", + "tools": [{ "type": "function", "function": { "...": "..." } }] +} +``` + +If the application needs both reasoning and tools: + +- migrate that flow to Responses when implementation changes are in scope; +- otherwise report it as a compatibility blocker; +- do not hide the incompatibility by removing tools, dropping required reasoning, or changing the workload's behavior without approval. + +If the live API rejects the intended `none` path, treat it as a current API compatibility issue and report the exact request and error rather than inventing a workaround. + +## Responses API and conversation state + +Prefer Responses for reasoning, tools, multi-turn agents, and new 5.6 capabilities. + +For ordinary multi-turn Responses calls, preserve the repository's existing state strategy. Do not add persisted reasoning merely because it exists. + +If deliberately enabling persisted reasoning: + +- use `reasoning.context: "all_turns"` only when the objective and assumptions remain stable; +- prefer `previous_response_id` when the server can carry state; +- when replaying manually, preserve every prior user input and every relevant output item, not only assistant text; +- with `store: false` or ZDR, request and replay `reasoning.encrypted_content`; +- use current-turn behavior when old reasoning may be stale or misleading. + +For manual replay, preserve item types, IDs, call IDs, caller metadata, and assistant phase values exactly. Incomplete replay can silently reduce quality or break tool continuation. + +## Prompt caching + +Do not assume old cache-hit behavior survives the model swap. + +GPT-5.6 implicit caching places a managed breakpoint near the latest user or tool message and no longer relies on 128-token rounding. A prompt with a large stable prefix followed by a changing suffix can therefore lose cache hits even when the stable prefix itself has not changed. + +Audit: + +- large reusable system/developer prompts; +- dynamic suffixes appended to otherwise stable prompts; +- changing timestamps, request IDs, user-specific values, or tool lists in the prefix; +- cache keys, retention settings, and cache dashboards; +- token accounting that assumes reads only and ignores writes. + +Migration rules: + +- keep reusable prefixes stable; +- do not churn large system prompts unnecessarily; +- compare old and new `cached_tokens`, `cache_write_tokens`, latency, and cost; +- use explicit cache breakpoints only when a measured workload has a stable boundary that implicit caching misses; +- do not globally convert every prompt to explicit caching; +- do not send 5.6-only cache fields to older routes in a mixed-model system. + +When old and GPT-5.6 routes share a request builder, isolate GPT-5.6-only fields instead of applying them globally. + +The new top-level request shape uses `prompt_cache_options`, for example: + +```json +{ + "prompt_cache_options": { + "mode": "explicit", + "ttl": "30m" + } +} +``` + +Place explicit breakpoints at the actual stable rendered boundary using `prompt_cache_breakpoint`. Preserve `prompt_cache_key` when the application already uses it. Treat the older `prompt_cache_retention` shape as deprecated and verify the live docs before rewriting it. + +Cache writes cost more than ordinary uncached input, so a lower hit rate can be both slower and more expensive. + +## Images, PDFs, files, and long context + +GPT-5.6 can change token and latency behavior without any prompt change: + +- for image inputs, omitted or `auto` image detail can preserve original dimensions; +- for PDF/file inputs in Responses, omitted or `input_file.detail: "auto"` can use high page-image detail; +- Chat Completions file inputs do not expose the same detail control; +- long-context Sol and Terra requests can cross pricing thresholds; +- Luna's smaller context can break workloads that fit in Sol or Terra. + +For multimodal or long-context usages: + +1. Measure input tokens and latency before and after. +2. Make detail explicit when cost or latency matters. +3. Resize images or use lower detail when the task does not need original spatial precision. +4. Keep original/high detail for dense, coordinate-sensitive, OCR, localization, or visual-inspection tasks where it materially improves quality. +5. Test worst-case context lengths, not only typical requests. + +Do not claim a capability was removed based only on a missing metadata flag. Verify against current docs and a representative request. + +## Structured outputs, parsers, and tool contracts + +Keep output contracts explicit: + +- preserve JSON schemas, required fields, enums, refusal handling, and parser expectations; +- preserve tool names, parameter schemas, call IDs, and retry behavior; +- keep citations, evidence fields, or native artifacts when downstream consumers require them; +- validate that the final answer still satisfies the contract, not merely that a tool call succeeded. + +Do not fix a failing migration by weakening a schema, deleting required behavior, removing routes, dropping tools, or changing business logic unless the user explicitly asked for that product change. + +## Optional: Pro mode + +Do not enable Pro mode during a baseline migration unless the old usage was Pro-like or the user explicitly asks for it. + +GPT-5.6 Pro uses the base model with a reasoning mode: + +```json +{ + "model": "gpt-5.6-sol", + "reasoning": { + "mode": "pro", + "effort": "medium" + } +} +``` + +Rules: + +- use Responses, not Chat Completions; +- do not search for or invent a separate `gpt-5.6-pro` slug; +- supported Pro efforts begin at `medium`; +- mode and effort are separate decisions; +- compare task quality, total latency, and actual billed token usage against standard mode. + +If migrating a legacy Pro slug, make the mode change explicit and evaluate it separately from ordinary Sol migration. + +## Optional: Programmatic Tool Calling + +Programmatic Tool Calling is not a required part of moving to GPT-5.6. Add it only when code can reduce large structured intermediate results before they return to model context. + +Good candidates: + +- bounded read-only filtering, joining, sorting, ranking, deduplication, and aggregation; +- batching many similar records; +- repeated deterministic validation; +- map-reduce style retrieval with a compact result schema. + +Poor candidates: + +- one direct tool call; +- adaptive workflows where each result changes the next decision; +- write, approval, or side-effecting flows; +- citation-heavy or native-artifact flows; +- semantic judgment that should remain visible to the model. + +Request-shape requirements: + +```json +{ + "tools": [ + { "type": "programmatic_tool_calling" }, + { + "type": "function", + "name": "lookup_records", + "allowed_callers": ["programmatic"] + } + ] +} +``` + +Do not nest `programmatic_tool_calling` under another `tools` property. When enabled, the host must handle `program`, program-issued `function_call`, `function_call_output`, and `program_output` items. Preserve the original `call_id` and `caller` when returning function results. + +Constrain the stage, eligible read-only tools, output schema, retry limit, and handoff back to direct judgment. Validate the final user-visible answer; a correct program result can still become an incorrect final answer. + +## Optional: multi-agent beta + +Do not enable multi-agent behavior during a baseline migration unless the application already has a clear parallelizable workflow and the user asks for it. + +Enabling it requires: + +- the `OpenAI-Beta: responses_multi_agent=v1` header; +- `multi_agent: { "enabled": true, "max_concurrent_subagents": 3 }`; +- handling `multi_agent_call`, `multi_agent_call_output`, and `agent_message` items; +- executing ordinary developer-defined function calls from any agent and returning all required outputs; +- preserving new items for replay and tracing; +- checking incompatibilities with compaction, reasoning summaries, and tool-call limits in current docs. + +Cap concurrency. Do not let a migration task create unbounded subagents, duplicate work, or finish without a final synthesis. + +## Prompt migration judgment + +After the model and API baseline is working, run representative traces before editing prompts. Change prompts only for measured failures. + +For GPT-5.6, prefer: + +- shorter, outcome-oriented prompts; +- explicit success criteria, dependencies, stopping conditions, and completion boundaries; +- preserved user-provided values; +- decision criteria for implicit choices instead of universal defaults or keyword maps; +- explicit autonomy and permission boundaries; +- explicit tool routing, resource links, breadcrumbs, and expected tool choice; +- staged plans, current-layer awareness, and concise handoffs for long work; +- real validation before declaring completion. + +Avoid: + +- generic `be brief`, `be thorough`, or `think step by step` instructions; +- blanket language instructions that can cause unwanted language switching; +- repeating `ask first` until safe local work becomes blocked; +- giant prompt rewrites that make the source of a regression impossible to identify; +- telling the model to minimize tool loops when correctness, evidence, or required validation needs more work. + +For coding or agentic migrations, add concrete preservation and verification rules: + +``` +Preserve existing functionality, routes, outputs, and user-visible behavior. +Do not delete or disable required behavior merely to make the build pass. +Before finishing, run the relevant build, tests, type checks, render or smoke +checks, and report the evidence. +``` + +For long-running work, define the current layer: research, design, implementation, review, or external coordination. Do not let the model silently move to another layer. + +## Upgrade workflow + +1. Fetch current live 5.6 docs and the Prompting Best Practices section. +2. Inventory every usage site and its adjacent prompt, config, registry, parser, and test surfaces. +3. Classify each usage by role and migration class. +4. Choose Sol, Terra, or Luna by the existing workload's role. +5. Preserve the old effective reasoning effort explicitly. +6. Run the compatibility gates: + - endpoint and SDK support; + - Chat Completions plus function tools; + - cache topology and cache fields; + - context length and long-context cost; + - image, PDF, and file detail; + - structured outputs and parsers; + - Responses state replay and tool continuation; + - mixed-model routing and unsupported new fields. +7. Apply the smallest safe model, config, registry, and prompt changes. +8. Do not add optional Pro, persisted reasoning, PTC, explicit caching, or multi-agent behavior unless needed and measurable. +9. Run existing tests and representative evals. +10. Report changed, unchanged, blocked, and confirmation-needed sites separately. + +## Validation matrix + +Prefer a controlled comparison: + +1. old model + old prompt + old settings; +2. GPT-5.6 target + same prompt + preserved effective reasoning; +3. GPT-5.6 target + same prompt + one lower effort; +4. GPT-5.6 target + the smallest prompt or API fix required by a measured failure; +5. optional feature treatment, isolated from the baseline. + +Measure what matters for the workflow: + +- task success and user-visible quality; +- structured-output validity and parser success; +- tool choice, tool arguments, retries, loop count, and completion rate; +- TTFT, end-to-end latency, timeout rate, and concurrency behavior; +- input, output, reasoning, cached, and cache-write tokens; +- cost per successful task; +- long-context, compaction, and replay behavior; +- image/PDF token use and visual/OCR accuracy; +- completeness, preserved behavior, citations, and validation evidence. + +For model routers and pickers, test at least one representative workload for each role. Verify that the cheapest or fastest tier is not accidentally used for quality-critical work and that Sol is not accidentally used for every workload. + +## Required final report + +Return: + +- `Current usage inventory`: each model site, endpoint, role, prompt surface, and old effective reasoning. +- `Target mapping`: Sol, Terra, Luna, unchanged, or confirmation-needed, with the reason. +- `Changes made`: model strings, reasoning settings, prompts, registries, metadata, tests, and API-shape changes. +- `Compatibility checks`: Chat Completions/tools, caching, state replay, multimodal detail, context/cost, schemas, and mixed-model routing. +- `Prompt changes`: each surgical edit and the failure mode it addresses. +- `Validation`: commands, evals, traces, before/after measurements, and remaining gaps. +- `Unchanged sites`: historical, pinned, ambiguous, or intentionally role-specific usages. +- `Blockers and open questions`: exact issue, why it is unsafe to guess, and the smallest next step. + +Never say the migration is complete merely because model strings changed. It is complete only when the affected behavior and contracts have been validated or the remaining gaps are stated explicitly. diff --git a/skills/.curated/openai-docs/scripts/resolve-latest-model-info b/skills/.curated/openai-docs/scripts/resolve-latest-model-info new file mode 100755 index 0000000..1190cba --- /dev/null +++ b/skills/.curated/openai-docs/scripts/resolve-latest-model-info @@ -0,0 +1,31 @@ +#!/bin/sh +set -eu + +SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +SCRIPT_PATH="$SCRIPT_DIR/resolve-latest-model-info.cjs" + +if [ -n "${NODE:-}" ] && [ -x "$NODE" ]; then + "$NODE" "$SCRIPT_PATH" "$@" + exit $? +fi + +if command -v node >/dev/null 2>&1; then + node "$SCRIPT_PATH" "$@" + exit $? +fi + +for CANDIDATE in \ + "$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node" \ + "$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/bin/node" \ + "/opt/homebrew/bin/node" \ + "/usr/local/bin/node" \ + "/usr/bin/node" +do + if [ -x "$CANDIDATE" ]; then + "$CANDIDATE" "$SCRIPT_PATH" "$@" + exit $? + fi +done + +echo "No usable Node runtime found for resolve-latest-model-info.cjs" >&2 +exit 127 diff --git a/skills/.curated/openai-docs/scripts/resolve-latest-model-info.js b/skills/.curated/openai-docs/scripts/resolve-latest-model-info.cjs old mode 100755 new mode 100644 similarity index 82% rename from skills/.curated/openai-docs/scripts/resolve-latest-model-info.js rename to skills/.curated/openai-docs/scripts/resolve-latest-model-info.cjs index 1bd16ac..498e19d --- a/skills/.curated/openai-docs/scripts/resolve-latest-model-info.js +++ b/skills/.curated/openai-docs/scripts/resolve-latest-model-info.cjs @@ -1,5 +1,7 @@ #!/usr/bin/env node +// Keep this entrypoint CommonJS-safe when the skill is copied into a type=module repo. + const fs = require("node:fs/promises"); const path = require("node:path"); @@ -36,15 +38,31 @@ async function readSource(source) { return fs.readFile(path.resolve(source), "utf8"); } - const response = await fetch(source, { - headers: { accept: "text/markdown,text/plain,*/*" }, - }); + let lastError; + for (let attempt = 1; attempt <= 3; attempt += 1) { + try { + const response = await fetch(source, { + headers: { accept: "text/markdown,text/plain,*/*" }, + }); - if (!response.ok) { - throw new Error(`failed to fetch ${source}: ${response.status}`); + if (response.ok) { + return response.text(); + } + + lastError = new Error("failed to fetch " + source + ": " + response.status); + if (response.status < 500 && response.status !== 429) { + break; + } + } catch (error) { + lastError = error; + } + + if (attempt < 3) { + await new Promise((resolve) => setTimeout(resolve, 250 * attempt)); + } } - return response.text(); + throw lastError; } function parseIndentedInfo(lines, startIndex) { diff --git a/skills/.system/openai-docs/SKILL.md b/skills/.system/openai-docs/SKILL.md index df395fb..d96aa87 100644 --- a/skills/.system/openai-docs/SKILL.md +++ b/skills/.system/openai-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: "openai-docs" -description: "Use when the user asks how to build with OpenAI products or APIs, asks about Codex itself or choosing Codex surfaces, needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; use OpenAI docs MCP tools for non-Codex docs questions, use the Codex manual helper first for broad Codex self-knowledge, and restrict fallback browsing to official OpenAI domains." +description: "Use when the user asks how to build with OpenAI products or APIs, asks about Codex itself or choosing Codex surfaces, needs up-to-date official documentation with citations, help choosing the latest model for a use case, latest/current/default-model prompting guidance, or model upgrade and prompt-upgrade guidance; use OpenAI docs MCP tools for non-Codex docs questions, use the Codex manual helper first for broad Codex self-knowledge, and restrict fallback browsing to official OpenAI domains." --- @@ -14,19 +14,30 @@ For requests to build, run, configure, debug, or implement an API-backed app, sc Use this skill directly for docs-only questions, citations, model/API guidance, conceptual explanations, and examples that do not require building or running an API-backed artifact. -## Workflow Configuration +For latest/current/default/unspecified model migration or prompting-guidance requests, complete the read-only latest-model resolver and guide fetch before the API-key credential gate. The credential gate still blocks edits, tests, and API-backed implementation until resolved; it does not block read-only retrieval of current model, migration, or prompting guidance. -### Source Priority +## First action for latest-model changes + +Before reading memory, inspecting the repo, fetching docs, or checking API credentials, classify the request: + +- **Latest/current prompting guidance, or change requested + latest/current/newest/recommended/default/flagship/unspecified target:** immediately execute `/scripts/resolve-latest-model-info` and inspect its JSON output. This includes asking how to prompt the latest model, changing prompts, a model picker, model references, an SDK integration, replacing an older named model with "the current model", or asking "which model should I migrate/upgrade to?". Do not directly fetch `latest-model.md` for this branch. +- **Pure model-selection question only, with no prompting guidance or requested change:** directly fetch `https://developers.openai.com/api/docs/guides/latest-model.md`; do not run the resolver. +- **Change requested + explicit target model:** preserve that target; do not run the latest-model resolver. For an explicit GPT-5.6 Sol or GPT-5.6-family migration, fetch the live GPT-5.6 model-guidance page and read `references/upgrading-to-gpt-5p6-sol.md` for skill-specific migration judgment. +- **Prompting or migration guidance for an explicitly named GPT-5-family model:** fetch `https://developers.openai.com/api/docs/guides/model-guidance?model=` through Docs MCP and extract the relevant migration section or the `## Prompting Best Practices` section through the next H2 heading. Do not substitute latest-model guidance. + +For the resolver branch, do not suppress or redirect its stdout. Success requires JSON containing `model`, `migrationGuideUrl`, and `promptingGuideUrl`; if the command exits without all three fields, run it once more before any fallback. + +## Source Priority - For Codex self-knowledge, use the Codex source route below; it owns when to use the manual helper, Docs MCP, or bounded uncertainty. - For non-Codex OpenAI docs questions, use `mcp__openaiDeveloperDocs__search_openai_docs` to find the most relevant doc pages. - For non-Codex OpenAI docs questions, fetch the relevant page with `mcp__openaiDeveloperDocs__fetch_openai_doc` before answering. If search is noisy, run a narrower Docs MCP search; when any plausible official OpenAI docs URL is known or found, try fetching that URL through Docs MCP before relying on web-search content. - For API reference, schema, parameter, or required-field questions, use `mcp__openaiDeveloperDocs__get_openapi_spec` when available to verify the API shape alongside the relevant guide or reference page. - Use `mcp__openaiDeveloperDocs__list_openai_docs` only when you need to browse or discover non-Codex pages without a clear query. -- For model-selection, "latest model", or default-model questions, fetch `https://developers.openai.com/api/docs/guides/latest-model.md` first. If that is unavailable, load `references/latest-model.md`. -- For model upgrades or prompt upgrades, run `node scripts/resolve-latest-model-info.js` only when the target is latest/current/default or otherwise unspecified; otherwise preserve the explicitly requested target. +- For latest/current prompting guidance, model upgrades, or prompt upgrades, apply the first-action classifier above. Run /scripts/resolve-latest-model-info rather than the implementation file. When `load_workspace_dependencies` is available, you may set `NODE` to its returned Node.js executable before running the wrapper, but do not depend on that tool being available or remembered. The wrapper uses `$NODE` when supplied, then PATH and bundled/system fallbacks. If it reports no usable runtime, call `load_workspace_dependencies` when available, set `NODE` to the returned Node.js executable, and retry the wrapper once. +- For docs-only model-selection questions that do not ask to change an app, project, repo, model configuration, or prompts, fetch `https://developers.openai.com/api/docs/guides/latest-model.md` first. If that is unavailable, load `references/latest-model.md`. - Preserve explicit target requests: if the user names a target model like "migrate to GPT-5.4", keep that requested target even if `latest-model.md` names a newer model. Mention newer guidance only as optional. -- If current remote guidance is needed, fetch both the returned migration and prompting guide URLs directly. If direct fetch fails, use MCP/search fallback; if that also fails, use bundled fallback references and disclose the fallback. +- If current remote guidance is needed, treat the returned migration and prompting guide URLs as opaque and fetch those exact URLs directly. Do not derive, substitute, or append a model query to them. If a prompting guide URL resolves to a combined model-guidance page, extract only the `## Prompting Best Practices` section through the next H2 heading. If a fetched guide contains only a title or no substantive body, retry the exact markdown URL through MCP/search fallback; if that also fails, use bundled fallback references and disclose the fallback. ## OpenAI product snapshots @@ -124,17 +135,16 @@ If MCP tools fail or no OpenAI docs resources are available: 1. Clarify whether the request is general docs lookup, model selection, a model-string upgrade, prompt-upgrade guidance, or broader API/provider migration. 2. For Codex self-knowledge requests, follow the Codex self-knowledge source procedure above. 3. For model-selection or upgrade requests, prefer current remote docs over bundled references when the user asks for latest/current/default guidance. - - Fetch `https://developers.openai.com/api/docs/guides/latest-model.md`. - - Find the latest model ID and explicit migration or prompt-guidance links. - - Prefer explicit links from the latest-model page over derived URLs. + - For docs-only model-selection questions, fetch `https://developers.openai.com/api/docs/guides/latest-model.md`, find the latest model ID and explicit migration or prompt-guidance links, and prefer explicit links over derived URLs. - For explicit named-model requests, preserve the requested model target. Mention newer remote guidance only as optional. - - For dynamic latest/current/default upgrades, run `node scripts/resolve-latest-model-info.js`, then fetch both returned guide URLs directly when possible. - - If direct guide fetch fails, use the developer-docs MCP tools or official OpenAI-domain search to find the same guide content. + - For latest/current/default prompting guidance or dynamic upgrades, run /scripts/resolve-latest-model-info as the first docs operation before any direct latest-model.md fetch or API-key credential gate, then fetch both returned guide URLs directly when possible. + - Fetch returned guide URLs exactly; do not derive or substitute model-specific URLs. + - If a direct guide fetch fails or returns only a title, use the developer-docs MCP tools or official OpenAI-domain search to find the same guide content. - If remote docs are unavailable, use bundled fallback references and say that fallback guidance was used. -4. For model upgrades, keep changes narrow: update active OpenAI API model defaults and directly related prompts only when safe. -5. Leave historical docs, examples, eval baselines, fixtures, provider comparisons, provider registries, pricing tables, alias defaults, low-cost fallback paths, and ambiguous older model usage unchanged unless the user explicitly asks to upgrade them. +4. For model upgrades, keep changes behavior-preserving and scoped: update active OpenAI API model defaults, directly related prompts, and the registries, routing, pricing, capability, or picker surfaces that the user actually placed in scope. +5. Leave historical docs, examples, eval baselines, fixtures, provider comparisons, intentionally pinned fallbacks, and ambiguous older model usage unchanged unless the user explicitly asks to upgrade them. Do not collapse a multi-model router or picker into one flagship model; preserve the existing cost, latency, and quality roles. 6. Keep SDK, tooling, IDE, plugin, shell, auth, and provider-environment migrations out of a model-and-prompt upgrade unless the user explicitly asks for them. -7. If an upgrade needs API-surface changes, schema rewiring, tool-handler changes, or implementation work beyond a literal model-string replacement and prompt edits, report it as blocked or confirmation-needed. +7. If a safe upgrade needs API-surface changes, schema rewiring, tool-handler changes, or broader implementation work, classify it explicitly. Make those changes when implementation is within the user's requested scope; otherwise report the exact blocker or confirmation needed instead of silently changing behavior. 8. For general docs lookup, start with a compact, title-like search query of 2-6 essential terms. Do not turn the full user question into a keyword list. Fetch the best page and exact section needed, and answer with concise citations. ## Reference map @@ -145,8 +155,9 @@ Read only what you need: - `scripts/fetch-codex-manual.mjs` -> current Codex manual fetch, verification, local temp cache, and outline generation. - `https://developers.openai.com/codex/codex-manual.md` -> current Codex self-knowledge synthesis, including setup, customization, skills, plugins, MCP, hooks, `AGENTS.md`, automations, and surface behavior; normally access it through the helper path and targeted file reads when temp caching is available. - `references/latest-model.md` -> bundled fallback for model-selection and "best/latest/current model" questions. -- `references/upgrade-guide.md` -> bundled fallback for model upgrade and upgrade-planning requests. -- `references/prompting-guide.md` -> bundled fallback for prompt rewrites and prompt-behavior upgrades. +- `references/upgrade-guide.md` -> bundled routing fallback for model upgrade and upgrade-planning requests. +- `references/upgrading-to-gpt-5p6-sol.md` -> GPT-5.6 Sol/family migration judgment, compatibility gates, optional feature boundaries, and validation. +- `references/prompting-guide.md` -> bundled GPT-5.6 prompting fallback plus the live Prompting Best Practices extraction contract. ## Quality rules diff --git a/skills/.system/openai-docs/references/latest-model.md b/skills/.system/openai-docs/references/latest-model.md index 04aa84b..b3b173d 100644 --- a/skills/.system/openai-docs/references/latest-model.md +++ b/skills/.system/openai-docs/references/latest-model.md @@ -6,17 +6,20 @@ This file is a curated helper. Every recommendation here must be verified agains | Model ID | Use for | | --- | --- | -| `gpt-5.5` | Latest/default text and reasoning model for most new apps, including coding and tool-heavy workflows | -| `gpt-5.5-pro` | Maximum reasoning or quality when latency and cost matter less | -| `gpt-5.4` | Previous default text and reasoning model; use for existing GPT-5.4 integrations | -| `gpt-5.4-mini` | Lower-cost testing and lighter production workflows | -| `gpt-5.4-nano` | High-throughput simple tasks and classification | -| `gpt-5.5` | Explicit no-reasoning text path via `reasoning.effort: none` | +| `gpt-5.6` | Latest/default GPT-5.6 alias; routes to Sol | +| `gpt-5.6-sol` | Flagship GPT-5.6 tier for hardest quality-first, coding, and reasoning workflows | +| `gpt-5.6-terra` | Mini-like GPT-5.6 tier for balanced cost, latency, and quality | +| `gpt-5.6-luna` | Nano-like GPT-5.6 tier for high-throughput, simple, or strict-latency tasks | +| `gpt-5.5` | Previous default text and reasoning model; use for existing GPT-5.5 integrations | +| `gpt-5.4` | Older default text and reasoning model; use for existing GPT-5.4 integrations | +| `gpt-5.4-mini` | Older lower-cost testing and lighter production workflows | +| `gpt-5.4-nano` | Older high-throughput simple tasks and classification | | `gpt-4.1-mini` | Cheaper no-reasoning text | | `gpt-4.1-nano` | Fastest and cheapest no-reasoning text | | `gpt-5.3-codex` | Agentic coding, code editing, and tool-heavy coding workflows | | `gpt-5.1-codex-mini` | Cheaper coding workflows | -| `gpt-image-1.5` | Best image generation and edit quality | +| `gpt-image-2` | Best image generation and edit quality | +| `gpt-image-1.5` | Less expensive image generation and edit quality | | `gpt-image-1-mini` | Cost-optimized image generation | | `gpt-4o-mini-tts` | Text-to-speech | | `gpt-4o-mini-transcribe` | Speech-to-text, fast and cost-efficient | @@ -32,5 +35,6 @@ This file is a curated helper. Every recommendation here must be verified agains ## Maintenance notes +- GPT-5.6 Pro is a Responses reasoning mode on the base model, not a separate `gpt-5.6-pro` slug. Verify the live model guide before recommending its request shape. - This file will drift unless it is periodically re-verified against current OpenAI docs. - If this file conflicts with current docs, the docs win. diff --git a/skills/.system/openai-docs/references/prompting-guide.md b/skills/.system/openai-docs/references/prompting-guide.md index 0d9273c..a9d407c 100644 --- a/skills/.system/openai-docs/references/prompting-guide.md +++ b/skills/.system/openai-docs/references/prompting-guide.md @@ -1,244 +1,287 @@ -GPT-5.5 works best when prompts define the outcome and leave room for the model to choose an efficient solution path. Compared with earlier models, you can often use shorter, more outcome-oriented prompts: describe what good looks like, what constraints matter, what evidence is available, and what the final answer should contain. +## Retrieve the live GPT-5.6 prompting guidance -Avoid carrying over every instruction from an older prompt stack. Legacy prompts often over-specify the process because earlier models needed more help staying on track. With GPT-5.5, that can add noise, narrow the model's search space, or lead to overly mechanical answers. +Use the OpenAI Docs MCP to fetch the live GPT-5.6 prompting guidance from: -For more detail on GPT-5.5 behavior changes, start with the [Using GPT-5.5 guide](/api/docs/guides/latest-model). This guide focuses on prompt changes that follow from those behavior changes. +https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6#prompting-best-practices -The patterns here are starting points. Adapt them to your product surface, tools, evals, and user experience goals. +Read only the `## Prompting Best Practices` section, stopping at the next H2 heading. The URL anchor points to the section visually, but the Docs MCP may return the full page, so explicitly extract only that section. -## Personality and behavior +Treat the live section as the canonical model-specific prompting guidance. Use the local guidance below only for skill-specific migration judgment: deciding what to preserve, remove, rewrite, or test when adapting an existing prompt stack to GPT-5.6. -GPT-5.5's default style is efficient, direct, and task-oriented. This is useful for production systems: responses stay focused, behavior is easier to steer, and the model avoids unnecessary conversational padding. +## Skill-specific migration judgment -For customer-facing assistants, support workflows, coaching experiences, and other conversational products, define both personality and collaboration style. +GPT-5.6 works best when prompts define the outcome, important constraints, available evidence, and completion bar, then leave room for the model to choose an efficient path. Compared with earlier GPT-5 models, many applications can use shorter prompts and smaller tool sets without losing quality. -- **Personality** controls how the assistant sounds: tone, warmth, directness, formality, humor, empathy, and level of polish. -- **Collaboration style** controls how the assistant works: when it asks questions, when it makes assumptions, how proactive it should be, how much context it gives, when it checks work, and how it handles uncertainty or risk. +Do not carry over every instruction from an older prompt stack. Legacy prompts often repeat rules, prescribe unnecessary steps, expose irrelevant tools, or include examples that no longer change behavior. With GPT-5.6, this can encourage extra exploration, repeated validation, and larger accumulated context. -Keep both short. Personality instructions should shape the user experience. Collaboration instructions should shape task behavior. Neither should replace clear goals, success criteria, tool rules, or stopping conditions. +Start with the smallest prompt and tool set that passes your evals. Add an instruction, example, or tool only when it fixes a measured failure mode. -Example personality block for a steady task-focused assistant: +## Simplify prompts first -```text -# Personality -You are a capable collaborator: approachable, steady, and direct. Assume the user is competent and acting in good faith, and respond with patience, respect, and practical helpfulness. +When migrating an existing prompt, remove redundant scaffolding before adding new GPT-5.6-specific instructions. -Prefer making progress over stopping for clarification when the request is already clear enough to attempt. Use context and reasonable assumptions to move forward. Ask for clarification only when the missing information would materially change the answer or create meaningful risk, and keep any question narrow. +Trim: -Stay concise without becoming curt. Give enough context for the user to understand and trust the answer, then stop. Use examples, comparisons, or simple analogies when they make the point easier to grasp. When correcting the user or disagreeing, be candid but constructive. When an error is pointed out, acknowledge it plainly and focus on fixing it. +- repeated statements of the same rule; +- generic “be thorough,” “be concise,” or “think step by step” language; +- examples that do not change behavior; +- process instructions for behavior the model already performs reliably; +- tools and tool descriptions unrelated to the task. -Match the user's tone within professional bounds. Avoid emojis and profanity by default, unless the user explicitly asks for that style or has clearly established it as appropriate for the conversation. -``` +Keep: -Example personality block for an expressive collaborative assistant: +- the user-visible outcome; +- success criteria and stopping conditions; +- safety, business, evidence, and permission constraints; +- tool-routing rules when the correct route is not obvious; +- required output shape and validation requirements. -```text -# Personality -Adopt a vivid conversational presence: intelligent, curious, playful when appropriate, and attentive to the user's thinking. Ask good questions when the problem is blurry, then become decisive once there is enough context. - -Be warm, collaborative, and polished. Conversation should feel easy and alive, but not chatty for its own sake. Offer a real point of view rather than merely mirroring the user, while staying responsive to their goals and constraints. - -Be thoughtful and grounded when the task calls for synthesis or advice. State a clear recommendation when you have enough context, explain important tradeoffs, and name uncertainty without becoming evasive. -``` - -For more expressive products, add warmth, curiosity, humor, or point of view explicitly, but keep the block short. Use personality to shape the experience, not to compensate for unclear goals or missing task instructions. - -## Improve time to first visible token with a preamble - -In streaming applications, users notice how long it takes before the first visible response appears. GPT-5.5 may spend time reasoning, planning, or preparing tool calls before emitting visible text. - -For longer or tool-heavy tasks, prompt the model to start with a short preamble: a brief visible update that acknowledges the request and states the first step. This can improve perceived responsiveness without changing the underlying task. - -Use this pattern when the task may take more than one step, require tool calls, or involve a long-running agent workflow. - -```text -Before any tool calls for a multi-step task, send a short user-visible update that acknowledges the request and states the first step. Keep it to one or two sentences. -``` - -For coding agents that expose separate message phases, you can be more explicit: - -```text -You must always start with an intermediary update before any content in the analysis channel if the task will require calling tools. The user update should acknowledge the request and explain your first step. -``` +Review the remaining instructions for contradictions. GPT-5-class models follow prompt contracts closely, so conflicting rules can create more instability than missing detail. ## Outcome-first prompts and stopping conditions -GPT-5.5 is strongest when the prompt defines the target outcome, success criteria, constraints, and available context, then lets the model choose the path. +Describe the destination rather than prescribing every step. GPT-5.6 can usually choose an efficient search, tool, or reasoning path when the prompt states what good looks like. -For many tasks, describe the destination rather than every step. This gives the model room to choose the right search, tool, or reasoning strategy for the task. +Prefer: -Prefer this: + Resolve the customer's issue end to end. -```text -Resolve the customer's issue end to end. + Success means: + - make the eligibility decision from available policy and account evidence + - complete any allowed action before responding + - return completed_actions, customer_message, and blockers + - if required evidence is missing, ask for the smallest missing field -Success means: -- the eligibility decision is made from the available policy and account data -- any allowed action is completed before responding -- the final answer includes completed_actions, customer_message, and blockers -- if evidence is missing, ask for the smallest missing field -``` +Avoid unnecessary absolute rules. Use ALWAYS, NEVER, must, and only for true invariants such as safety rules, required fields, or actions that should never happen. For judgment calls, such as when to search, ask, use a tool, or keep iterating, prefer decision rules. -**Avoid unnecessary absolute rules.** Older prompts often use strict instructions like `ALWAYS`, `NEVER`, `must`, and `only` to control model behavior. Use those words for true invariants, such as safety rules, required output fields, or actions that should never happen. For judgment calls, such as when to search, ask for clarification, use a tool, or keep iterating, prefer decision rules instead. +Preserve explicit user values. When the correct value is implicit, provide decision criteria and let the model reason from context or schema. Avoid universal defaults, keyword maps, and broad semantic shortcuts. -Avoid this style of instruction unless every step is truly required: +Add stopping conditions: -```text -First inspect A, then inspect B, then compare every field, then think through -all possible exceptions, then decide which tool to call, then call the tool, -then explain the entire process to the user. -``` + Resolve the request in the fewest useful tool loops, but do not let loop + minimization outrank correctness, required evidence, calculations, or + required citations. -Add explicit stopping conditions: + After each result, ask whether the core request can now be answered with + useful evidence. If yes, answer. If required evidence is still missing, + name the missing fact and use the smallest useful fallback. -```text -Resolve the user query in the fewest useful tool loops, but do not let loop minimization outrank correctness, accessible fallback evidence, calculations, or required citation tags for factual claims. +## Personality, collaboration, and response length -After each result, ask: "Can I answer the user's core request now with useful evidence and citations for the factual claims?" If yes, answer. -``` +GPT-5.6 is efficient, direct, and more compressed than recent models. For customer-facing assistants and collaborative products, define both personality and collaboration style. -Define missing-evidence behavior: +- Personality controls tone, warmth, directness, formality, humor, empathy, and polish. +- Collaboration style controls when the model asks questions, makes assumptions, takes initiative, explains tradeoffs, checks work, and handles uncertainty. -```text -Use the minimum evidence sufficient to answer correctly, cite it precisely, then stop. -``` +Keep both short. Personality should shape the user experience; collaboration instructions should shape task behavior. Neither should replace clear goals, success criteria, tool rules, or stopping conditions. -## Formatting +Use concrete writing controls: -GPT-5.5 is highly steerable on output format and structure. Use that control when it improves comprehension or product fit. + Lead with the conclusion. Include the evidence needed to support it, any + material caveat, and the next action. Keep all required facts, decisions, + caveats, and next steps. Trim introductions, repetition, generic reassurance, + and optional background first. -Set `text.verbosity`, describe the expected output shape, and reserve heavier structure for cases where it improves comprehension or your product UI needs a stable artifact. The API default for `text.verbosity` is `medium`; use `low` when you prefer shorter, more concise responses. +Avoid generic “be brief,” “keep it short,” or “use minimal text” instructions. GPT-5.6 is already biased toward compression, and generic brevity can make it omit required evidence or parts of an artifact. -Plain conversational formatting: +For customer-facing tone, prefer concrete guidance: -```text -Let formatting serve comprehension. Use plain paragraphs as the default format for normal conversation, explanations, reports, documentation, and technical writeups. Keep the presentation clean and readable without making the structure feel heavier than the content. + Be direct and tactful. Acknowledge friction specifically when relevant. + Avoid canned reassurance and unnecessary sign-offs. -Use headers, bold text, bullets, and numbered lists sparingly. Reach for them when the user requests them, when the answer needs clear comparison or ranking, or when the information would be harder to scan as prose. Otherwise, favor short paragraphs and natural transitions. +Avoid blanket language rules such as “always respond in the user's language” unless that is truly the product requirement. Specify the intended output language and when it should change. -Respect formatting preferences from the user. If they ask for a terse answer, minimal formatting, no bullets, no headers, or a specific structure, follow that preference unless there is a strong reason not to. -``` +For editing, rewriting, summaries, and customer-facing drafts, tell the model what to preserve: -Add explicit audience and length guidance: + Preserve the requested artifact, length, structure, genre, and factual claims + first. Improve clarity, flow, and correctness without adding new claims, + sections, or a more promotional tone unless requested. -```text -Write for a senior business audience. Keep the answer under 400 words. Use short paragraphs and only include bullets when they improve scannability. Prioritize the conclusion first, then the reasoning, then caveats. -``` +## Autonomy and permissions -For editing, rewriting, summaries, or customer-facing messages, tell the model what to preserve before asking it to improve style. This pattern is useful when you want polish without expansion. +GPT-5.6 can be proactive and persistent. Define which level of action each request authorizes. -```text -Preserve the requested artifact, length, structure, and genre first. Quietly improve clarity, flow, and correctness. Do not add new claims, extra sections, or a more promotional tone unless explicitly requested. -``` + For requests to answer, explain, review, diagnose, or plan, inspect the + relevant materials and report the result. Do not implement changes unless + the request also asks for them. + + For requests to change, build, or fix, make the requested in-scope local + changes and run relevant non-destructive validation without asking first. + + Require confirmation for external writes, destructive actions, purchases, + or a material expansion of scope. + +Specify which local actions are safe without approval, such as reading files, inspecting logs, searching, editing in-scope code, and running non-destructive tests. + +Avoid repeating “ask first” throughout the prompt. Repetition can cause unnecessary permission checks even for safe, expected actions. + +For long-running work, define the current layer of work. Distinguish research, design, implementation, review, and external coordination so the model does not silently move from one layer to another. + +## Tool routing + +Expose only task-relevant tools. Tool descriptions should state what the tool does, when to use it, important return fields, and error behavior. + +When correctness depends on prerequisite retrieval or lookup, say so: + + Before taking an action, resolve required discovery, retrieval, and + validation steps. Do not skip a prerequisite because the intended final + state seems obvious. + +When several reads are independent, parallelize them. When one result determines the next action, keep the work sequential. After parallel retrieval, synthesize before acting. + +If a tool returns empty, partial, or suspiciously narrow results, try one or two meaningful fallbacks before concluding that no result exists. + +## Programmatic Tool Calling + +Programmatic Tool Calling is useful when code can reduce large, structured intermediate results before they return to model context. + +Use it for: + +- filtering, joining, sorting, ranking, deduplication, and aggregation; +- batching across many similar records; +- repeated deterministic validation; +- large structured results that can be reduced to a compact schema. + +Prefer direct tool calls when: + +- one call is sufficient; +- intermediate outputs are already small; +- each result may change the next decision; +- an action requires approval; +- the final answer must preserve citations or native artifacts; +- the workflow requires semantic judgment between calls. + +Do not rely on generic instructions such as “use Programmatic Tool Calling efficiently.” State the bounded stage, eligible tools, output schema, retry limit, stop condition, and handoff back to direct model judgment. + + Use Programmatic Tool Calling only for the bounded record-reduction stage. + Call only the documented read-only tools. Filter and deduplicate the + intermediate results, then emit exactly the required compact schema with + evidence fields. Retry transient failures at most twice. Use direct tool + calls for approval, semantic judgment, citations, and final validation. + +Evaluate the final user-visible answer, not only the program result. Lower tokens, latency, calls, or turns are improvements only when the final answer still meets the required quality bar. ## Grounding, citations, and retrieval budgets -For grounded answers, citation behavior should be part of the prompt. Define what needs support, what counts as enough evidence, and how the model should behave when evidence is missing. Absence of evidence shouldn't automatically become a factual "no." For more details and examples, see the [citation formatting guide](/api/docs/guides/citation-formatting). +For grounded answers, citation behavior should be part of the prompt. Define what needs support, what counts as enough evidence, and how to behave when evidence is missing. Absence of evidence should not automatically become a factual “no.” -### Add an explicit retrieval budget + For ordinary Q&A, start with one broad search using short, discriminative + keywords. If the top results contain enough support for the core request, + answer from those results. -Retrieval budgets are stopping rules for search. They tell the model when enough evidence is enough. + Make another retrieval call only when a required fact, owner, date, ID, or + source is missing; the user asked for exhaustive coverage or comparison; a + specific artifact must be read; or an important claim would otherwise be + unsupported. -```text -For ordinary Q&A, start with one broad search using short, discriminative keywords. If the top results contain enough citable support for the core request, answer from those results instead of searching again. + Do not search again only to improve phrasing, add examples, or support + nonessential detail. -Make another retrieval call only when: -- The top results do not answer the core question. -- A required fact, parameter, owner, date, ID, or source is missing. -- The user asked for exhaustive coverage, a comparison, or a comprehensive list. -- A specific document, URL, email, meeting, record, or code artifact must be read. -- The answer would otherwise contain an important unsupported factual claim. +For research and synthesis: -Do not search again to improve phrasing, add examples, cite nonessential details, or support wording that can safely be made more generic. -``` +- cite only retrieved sources; +- attach citations to the claims they support; +- label inference separately from directly supported facts; +- state conflicts between sources; +- narrow the answer or report missing evidence instead of guessing. -## Creative drafting guardrails +For creative drafting, distinguish source-backed facts from creative wording. Do not invent names, metrics, dates, roadmap status, customer outcomes, or product capabilities to make a draft sound stronger. -For drafting tasks, tell the model which claims must come from sources and which parts may be creatively written. This is especially important for slides, launch copy, customer summaries, talk tracks, leadership blurbs, and narrative framing. +## Long-running workflows and state -```text -For creative or generative requests such as slides, leadership blurbs, outbound copy, summaries for sharing, talk tracks, or narrative framing, distinguish source-backed facts from creative wording. +For multi-step or tool-heavy tasks, prompt for a short visible preamble before the first tool call, then sparse outcome-based updates at major phase changes. Do not ask the model to narrate routine tool calls. -- Use retrieved or provided facts for concrete product, customer, metric, roadmap, date, capability, and competitive claims, and cite those claims. -- Do not invent specific names, first-party data claims, metrics, roadmap status, customer outcomes, or product capabilities to make the draft sound stronger. -- If there is little or no citable support, write a useful generic draft with placeholders or clearly labeled assumptions rather than unsupported specifics. -``` + Before tool calls for a multi-step task, send a one- or two-sentence + user-visible update that states the first step. During the task, update only + when a major phase begins or a finding changes the plan. Each update should + state one concrete outcome and the next step. -## Frontend engineering and visual taste +Preserve assistant phase values when replaying history so the model can distinguish commentary from the final answer. If using previous_response_id, prior assistant state is preserved automatically. If replaying history manually, preserve each original phase value unchanged. -For frontend work, refer to the [example instructions](/api/docs/guides/frontend-prompt) for practical ways to steer UI quality. They cover product and user context, design-system alignment, first-screen usability, familiar controls, expected states, responsive behavior, and common generated-UI defaults to avoid, such as generic heroes, nested cards, decorative gradients, visible instructional text, and broken layouts. +Compact after major milestones rather than every turn. Keep the prompt functionally consistent after compaction and treat compacted items as opaque state. -## Prompt the model to check its work +Persisted reasoning is useful when the objective, assumptions, and priorities remain stable across turns. Use current-turn behavior when earlier reasoning is no longer relevant. Do not treat persisted reasoning as an always-on optimization: stale reasoning can add tokens, increase latency, and anchor the model to an outdated approach. -Give GPT-5.5 access to tools that let it check outputs when validation is possible. +Prompt caching also affects prompt construction. Keep reusable prefixes stable and avoid unnecessary churn in large system prompts. Use explicit cache breakpoints only when they improve measured cache behavior and cost for the workload. -For coding agents, ask for concrete validation commands: +## Reasoning effort -```text -After making changes, run the most relevant validation available: -- targeted unit tests for changed behavior -- type checks or lint checks when applicable -- build checks for affected packages -- a minimal smoke test when full validation is too expensive +Treat reasoning effort as a last-mile tuning knob, not the first response to a weak result. -If validation cannot be run, explain why and describe the next best check. -``` +- Preserve the current GPT-5.5 or GPT-5.4 reasoning effort as the baseline. +- Test the same setting and one level lower on representative tasks. +- Use low for latency-sensitive work when it preserves quality. +- Use medium as a balanced starting point. +- Use high or xhigh only when evals show a meaningful gain. +- Reserve max for the hardest quality-first workloads; do not recommend it globally. -For visual artifacts, ask for inspection after rendering: +Before increasing reasoning effort, check whether the prompt is missing a success criterion, dependency rule, tool-routing rule, or verification loop. -```text -Render the artifact before finalizing. Inspect the rendered output for layout, clipping, spacing, missing content, and visual consistency. Revise until the rendered output matches the requirements. -``` +## Frontend and visual tasks -For engineering and planning tasks, make implementation plans traceable: +GPT-5.6 has stronger layout, visual hierarchy, and design judgment. Still provide product context, preserve the existing design system, and name the states and constraints that matter. -```text -For implementation plans, include: -- requirements and where each is addressed -- named resources, files, APIs, or systems involved -- state transitions or data flow where relevant -- validation commands or checks -- failure behavior -- privacy and security considerations -- open questions that materially affect implementation -``` +For incremental frontend changes: -## Phase parameter +- inspect and preserve existing design tokens, components, and patterns; +- do not add extra features or decorative UI unless requested; +- preserve responsive behavior and expected states; +- render and inspect the result before finalizing. -Starting with GPT-5.4, long-running or tool-heavy Responses workflows can use assistant-item `phase` values to distinguish intermediate updates from final answers. GPT-5.5 uses the same pattern. +For vision, computer use, localization, or OCR tasks where spatial precision matters, choose image detail intentionally. Use original detail for large, dense, or coordinate-sensitive images when the extra input cost and latency are justified. -If you use `previous_response_id`, the API preserves prior assistant state automatically. If your application manually replays assistant output items into the next request, preserve each original `phase` value and pass it back unchanged. This matters most when a response includes preambles, repeated tool calls, or a final answer after intermediate assistant updates. +## Check work before finishing -```text -If manually replaying assistant items: -- Preserve assistant `phase` values exactly. -- Use `phase: "commentary"` for intermediate user-visible updates. -- Use `phase: "final_answer"` for the completed answer. -- Do not add `phase` to user messages. -``` +Give GPT-5.6 access to tools that can validate the output, and state what validation matters. + +For coding: + + After making changes, run the most relevant validation available: + - targeted tests for changed behavior + - type checks or lint checks when applicable + - build checks for affected packages + - a minimal smoke test when full validation is too expensive + + If validation cannot be run, explain why and describe the next best check. + +For visual artifacts: + + Render the artifact before finalizing. Inspect layout, clipping, spacing, + missing content, and visual consistency. Revise until the rendered output + matches the requirements. + +For implementation plans, include requirements, named resources or files, state transitions or data flow, validation checks, failure behavior, privacy or security considerations, and open questions that materially affect implementation. ## Suggested prompt structure Use this structure as a starting point for complex prompts. Keep each section short. Add detail only where it changes behavior. -```text -Role: [1-2 sentences defining the model's function, context, and job] + Role: [the model's function and context] -# Personality -[tone, demeanor, and collaboration style] + Personality: [tone and collaboration style] -# Goal -[user-visible outcome] + Goal: [user-visible outcome] -# Success criteria -[what must be true before the final answer] + Success criteria: [what must be true before the final answer] -# Constraints -[policy, safety, business, evidence, and side-effect limits] + Constraints: [policy, safety, business, evidence, and side-effect limits] -# Output -[sections, length, and tone] + Tools: [which tools to use, when, and what not to use] -# Stop rules -[when to retry, fallback, abstain, ask, or stop] -``` + Output: [sections, length, format, and tone] + + Stop rules: [when to retry, fallback, abstain, ask, or stop] + +## Prompt migration workflow + +When moving an existing application to GPT-5.6: + +1. Switch the model and preserve the current reasoning effort. +2. Run representative evals before changing the prompt. +3. Remove obsolete scaffolding, repeated instructions, and irrelevant tools. +4. Add only the smallest targeted instruction that fixes a measured regression. +5. Re-run evals after each prompt or reasoning change. + +Do not rewrite a working prompt stack all at once. Otherwise you cannot tell whether a behavior change came from the model, reasoning setting, prompt, tool set, or runtime. + +When a prompt regresses, debug it with a small set of real traces. Identify the failure mode, find the instruction or contradiction that likely caused it, make a surgical edit, and rerun the same cases. diff --git a/skills/.system/openai-docs/references/upgrade-guide.md b/skills/.system/openai-docs/references/upgrade-guide.md index b29f137..8134bc6 100644 --- a/skills/.system/openai-docs/references/upgrade-guide.md +++ b/skills/.system/openai-docs/references/upgrade-guide.md @@ -1,181 +1,22 @@ -# Upgrading to GPT-5.5 +# Model upgrade guidance -Use this guide when the user explicitly asks to upgrade an existing integration to GPT-5.5. Pair it with current OpenAI docs lookups. The default target string is `gpt-5.5`. +Use this file only as a bundled routing fallback when the live migration guide cannot be fetched. -## Freshness check +For latest, current, default, or unspecified-model upgrades: -Before applying this bundled guide for a latest/current/default model upgrade, run `node scripts/resolve-latest-model-info.js` from the OpenAI Docs skill directory. +1. Run `scripts/resolve-latest-model-info`. +2. Fetch the returned `migrationGuideUrl` and `promptingGuideUrl` exactly. +3. Treat the live guides as canonical. +4. If remote retrieval fails, disclose that bundled fallback guidance is being used. -- If the command returns `modelSlug: "gpt-5p5"`, continue with this bundled guide and use `references/prompting-guide.md` when prompt updates are needed. -- If the command returns a different `modelSlug`, fetch both the returned `migrationGuideUrl` and `promptingGuideUrl` and use them as the current source of truth instead of the bundled references. -- If the command fails, metadata is missing, or either remote guide cannot be fetched, continue with bundled fallback references and say the remote freshness check was unavailable. -- If the user explicitly named a target model, preserve that target and use current docs only to check compatibility or caveats. +For an explicit GPT-5.6 Sol or GPT-5.6-family migration: -## Upgrade posture +1. Preserve the user's explicit target; do not run the latest-model resolver. +2. Fetch the live GPT-5.6 model guidance: -Upgrade with the narrowest safe change set: + https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6 -- replace the model string first -- update only the prompts that are directly tied to that model usage -- do not automatically upgrade older or ambiguous model usages that may be intentionally pinned, such as historical docs, examples, tests, eval baselines, comparison code, or low-cost fallback/routing paths. Unless the user explicitly asks to upgrade all model usage, leave those sites unchanged and list them as confirmation-needed -- prefer prompt-only upgrades when possible -- if the upgrade would require API-surface changes, parameter rewrites, tool rewiring, provider migration, or broader code edits, mark it as blocked instead of stretching the scope +3. Read `references/upgrading-to-gpt-5p6-sol.md` for skill-specific migration judgment. +4. Read `references/prompting-guide.md` only when prompt changes are needed. -## Upgrade workflow - -1. Inventory current model usage. - - Search for model strings, client calls, and prompt-bearing files. - - Include inline prompts, prompt templates, YAML or JSON configs, Markdown docs, and saved prompts when they are clearly tied to a model usage site. -2. Pair each model usage with its prompt surface. - - Prefer the closest prompt surface first: inline system or developer text, then adjacent prompt files, then shared templates. - - If you cannot confidently tie a prompt to the model usage, say so instead of guessing. -3. Classify the source model family. - - Common buckets: GPT-5.4, GPT-5.3-Codex or GPT-5.2-Codex, earlier GPT-5.x, GPT-4o or GPT-4.1, reasoning models such as o1 or o3 or o4-mini, third-party model, or mixed and unclear. -4. Decide the upgrade class. - - `model string only` - - `model string + light prompt rewrite` - - `blocked without code changes` -5. Run the compatibility gate. - - Check whether the current integration can accept `gpt-5.5` without API-surface changes or implementation changes. - - Check whether structured outputs, tool schemas, function names, and downstream parsers can remain unchanged. - - For long-running Responses or tool-heavy agents, check whether `phase` is already preserved or round-tripped when the host replays assistant items or uses preambles. - - If compatibility depends on code changes, return `blocked`. - - If compatibility is unclear, return `unknown` rather than improvising. -6. Apply the upgrade when it is in scope. - - Default replacement string: `gpt-5.5`. - - Keep the intervention small and behavior-preserving. - - Start from the current reasoning effort when it is visible unless there is a measured reason to change it. - - For in-scope changes, update the model string and directly related prompts. - - For blocked or unknown changes, do not edit; report the blocker or uncertainty. -7. Summarize the result. - - `Current model usage` - - `Model-string updates` - - `Reasoning-effort handling` - - `Prompt updates` - - `Structured output and formatting assessment` - - `Tool-use assessment` when the flow uses tools, retrieval, or terminal actions - - `Phase assessment` when the flow is long-running, replayed, or tool-heavy - - `Compatibility check` - - `Validation performed` - -Output rule: - -- For each usage site, state the starting reasoning-effort recommendation. -- If the repo exposes the current reasoning setting, recommend preserving it first unless current OpenAI docs say otherwise. -- If the repo does not expose the current setting, recommend not adding one unless current OpenAI docs require it. - -## Upgrade outcomes - -### `model string only` - -Choose this when: - -- the source model is GPT-5.4 -- the existing prompts are already short, explicit, and task-bounded -- the workflow does not rely on strict output formats, tool-call behavior, batch completeness, or long-horizon execution that should be validated after the upgrade -- there are no obvious compatibility blockers - -Default action: - -- replace the model string with `gpt-5.5` -- preserve the current reasoning effort -- keep prompts unchanged -- validate behavior with existing tests, realistic spot checks, or an existing eval suite when one is already available - -### `model string + light prompt rewrite` - -Choose this when: - -- the task needs stronger completeness, citation discipline, verification, or dependency handling -- the upgraded model becomes too verbose, too dense, or hard to scan unless formatting is constrained -- the workflow has strict output shape requirements and lacks an explicit format contract, schema, or parser validation -- the workflow is research-heavy and needs stronger handling of sparse or empty retrieval results -- the workflow is coding-oriented, terminal-based, tool-heavy, or multi-agent, but the existing API surface and tool definitions can remain unchanged - -Default action: - -- replace the model string with `gpt-5.5` -- preserve the current reasoning effort for the first pass -- make only the smallest prompt edits needed for the observed workflow risk -- read the [GPT-5.5 prompting guide](/api/docs/guides/prompt-guidance?model=gpt-5.5) to choose the smallest prompt changes that recover or improve behavior -- avoid broad prompt cleanup unrelated to the upgrade -- for research workflows, add citation rules, retrieval budgets, missing-evidence behavior, and validation guidance from the prompting guide -- for dependency-aware or tool-heavy workflows, add prerequisite checks, missing-context handling, explicit tool budgets, stop conditions, and validation guidance -- for coding or terminal workflows, add repo-specific constraints, acceptance criteria, and concrete validation commands -- for multi-agent support or triage workflows, add task ownership, handoff, completeness, and stopping criteria -- for long-running Responses agents with preambles or multiple assistant messages, explicitly review whether `phase` is already handled; if adding or preserving `phase` would require code edits, mark the path as `blocked` -- do not classify a coding or tool-using Responses workflow as `blocked` just because the visible snippet is minimal; prefer `model string + light prompt rewrite` unless the repo clearly shows that a safe GPT-5.5 path would require host-side code changes - -### `blocked` - -Choose this when: - -- the upgrade appears to require API-surface changes -- the upgrade appears to require parameter rewrites or reasoning-setting changes that are not exposed outside implementation code -- the upgrade would require changing tool definitions, tool handler wiring, or schema contracts -- the user is asking for a tooling, IDE, plugin, shell, or environment migration rather than a model and prompt migration -- the integration depends on provider-specific APIs that do not map to the current OpenAI API surface without implementation work -- you cannot confidently identify the prompt surface tied to the model usage - -Default action: - -- do not improvise a broader upgrade -- report the blocker and explain that the fix is out of scope for this guide -- if useful, describe the smallest follow-up implementation task that would unblock the migration - -## Compatibility checklist - -Before applying or recommending a model-and-prompt-only upgrade, check: - -1. Can the current host accept the `gpt-5.5` model string without changing client code or API surface? -2. Are the related prompts identifiable and editable? -3. Does the host depend on behavior that likely needs API-surface changes, parameter rewrites, provider migration, or tool rewiring? -4. Would the likely fix be prompt-only, or would it need implementation changes? -5. Is the prompt surface close enough to the model usage that you can make a targeted change instead of a broad cleanup? -6. Do strict structured outputs, schemas, or downstream parsers still have an explicit contract? -7. For long-running Responses or tool-heavy agents, is `phase` already preserved if the host relies on preambles, replayed assistant items, or multiple assistant messages? -8. Are latency, token, or price assumptions validated by tests, realistic spot checks, or an existing eval suite rather than inferred from general model positioning? - -If item 1 is no, items 3 through 4 point to implementation work, or item 7 is no and the fix needs code changes, return `blocked`. - -If item 2 is no, return `unknown` unless the user can point to the prompt location. - -Important: - -- Existing use of tools, agents, or multiple usage sites is not by itself a blocker. -- If the current host can keep the same API surface and the same tool definitions, prefer `model string + light prompt rewrite` over `blocked`. -- Reserve `blocked` for cases that truly require implementation changes, not cases that only need stronger prompt steering. -- Do not claim token savings without task-level validation. - -## Scope boundaries - -This guide may: - -- update or recommend updated model strings -- update or recommend updated prompts -- inspect code and prompt files to understand where those changes belong -- inspect whether existing Responses flows already preserve `phase` -- flag compatibility blockers -- propose validation with existing tests, realistic spot checks, or existing eval suites - -This guide may not: - -- move Chat Completions code to Responses -- move Responses code to another API surface -- migrate SDKs, APIs, IDE configuration, shell hooks, plugins, or provider-specific tooling -- rewrite parameter shapes -- change tool definitions or tool-call handling -- change structured-output wiring -- add or retrofit `phase` handling in implementation code -- edit business logic, orchestration logic, SDK usage, IDE configuration, shell hooks, or plugin integration behavior except for model-string replacements and directly related prompt edits - -If a safe GPT-5.5 upgrade requires any of those changes, mark the path as blocked and out of scope. - -## Validation plan - -- Validate each upgraded usage site with existing tests, realistic spot checks, or an existing eval suite when one is already available. -- Compare against the current GPT-5.4 baseline when available. -- Check task success, retry count, tool-call count, total tokens, latency, output shape, and user-visible quality. -- For specialized workflows, validate the contract that matters most instead of judging only general output quality. -- If prompt edits were added, confirm each block is doing real work instead of adding noise. -- If the workflow has downstream impact, add a lightweight verification pass before finalization. +For another explicit model target, preserve that target and fetch its current official guidance. Do not reuse GPT-5.6-specific defaults, API shapes, or compatibility rules for a different model. diff --git a/skills/.system/openai-docs/references/upgrading-to-gpt-5p6-sol.md b/skills/.system/openai-docs/references/upgrading-to-gpt-5p6-sol.md new file mode 100644 index 0000000..4cff512 --- /dev/null +++ b/skills/.system/openai-docs/references/upgrading-to-gpt-5p6-sol.md @@ -0,0 +1,448 @@ +# Upgrading to GPT-5.6 Sol + +Use this guide when the user asks to migrate an existing OpenAI API integration, repository, prompt stack, agent, model router, or model picker to GPT-5.6 Sol or the GPT-5.6 family. + +The default explicit target is `gpt-5.6-sol`. The alias `gpt-5.6` routes to Sol; use it only when the repository intentionally prefers family aliases. Do not treat every old model usage as a Sol candidate: GPT-5.6 is a family with different cost, latency, context, and quality roles. + +Before changing code, use the OpenAI Docs MCP to fetch the current live GPT-5.6 model guidance: + +https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6 + +For prompt changes, also read only the `## Prompting Best Practices` section from: + +https://developers.openai.com/api/docs/guides/model-guidance?model=gpt-5.6#prompting-best-practices + +Treat live docs as canonical for current model IDs, parameters, limits, pricing, and feature availability. This file supplies migration judgment: where to look, what can break, what to preserve, what not to adopt automatically, and how to validate the result. + +## Core principle + +Do not perform a blind model-string replacement. + +First preserve the behavior, latency class, cost class, reasoning level, endpoint contract, tool semantics, cache behavior, and output contract of each usage site. Then make the smallest safe migration. Adopt new GPT-5.6 capabilities only when they solve a measured problem or the user explicitly asks for them. + +A model upgrade alone does not authorize adding reasoning fields, changing request schemas, or rewriting tests. Only add explicit reasoning when the old effective behavior is established and omission would change behavior on GPT-5.6. + +The main 5.6 migration hazards are: + +- choosing Sol for workloads that were intentionally mini, nano, low-cost, or latency-sensitive; +- inheriting 5.6's default `medium` reasoning where the old effective effort was `none`; +- using Chat Completions with function tools without explicitly setting effective reasoning to `none`; +- losing prompt-cache hits when a stable prefix is followed by a changing suffix; +- increasing image or PDF input tokens because omitted or `auto` detail behaves differently; +- applying new cache, persisted-reasoning, Pro, Programmatic Tool Calling, or multi-agent fields to routes that do not support them; +- updating model strings but forgetting registries, allowlists, pricing metadata, capability flags, tests, and UI model pickers. + +## Migration posture + +Classify every usage site before editing: + +1. `simple Sol migration` + - One flagship model usage. + - Same endpoint and request shape can remain. + - Reasoning effort is explicit or its old effective value is known. + - No cache, vision, file, tool, or parser behavior needs implementation changes. +2. `tier-aware family migration` + - The repository exposes multiple model roles, model choices, fallbacks, routers, pricing data, or capability metadata. + - Map each role to Sol, Terra, or Luna instead of replacing everything with Sol. +3. `compatibility migration` + - The safe move requires parameter, endpoint, cache, state, tool-loop, or multimodal-detail changes. + - Make these changes only when implementation work is inside the user's requested scope. Otherwise report the exact blocker and smallest follow-up. +4. `prompt migration` + - The API shape can remain, but representative traces show a prompt-specific regression. + - Make a surgical prompt edit tied to that failure; do not rewrite a working prompt stack wholesale. + - When the task is to update prompting guidance, edit the directly tied prompt surface only. Do not modify runtime request code, model schemas, or tests unless the prompt change requires it. +5. `optional feature adoption` + - Pro mode, persisted reasoning, explicit caching, Programmatic Tool Calling, or multi-agent behavior is being added deliberately. + - Keep this separate from the baseline migration so its effect can be measured. +6. `leave unchanged` + - Historical examples, documentation about old models, snapshots, fixtures, eval baselines, comparison code, intentionally pinned fallbacks, unsupported providers, or ambiguous usages. + +When intent is unclear, prefer leaving a usage unchanged and list it for confirmation over silently changing its role. + +## Inventory before editing + +Search for more than literal model IDs. Inventory: + +- model strings, aliases, environment variables, CLI flags, config defaults, and deployment settings; +- SDK calls to Responses, Chat Completions, Batch, or provider adapters; +- reasoning settings, token budgets, sampling settings, and latency timeouts; +- function tools, hosted tools, structured outputs, response parsers, and replay logic; +- system, developer, user, and tool-description prompts tied to each usage; +- routers, fallbacks, model allowlists, enums, regexes, validation schemas, and capability maps; +- model picker UI, display labels, descriptions, context limits, pricing metadata, and provider catalogs; +- prompt-cache keys, retention options, stable-prefix construction, and cache metrics; +- image, PDF, file, OCR, and computer-use inputs; +- tests, fixtures, snapshots, evals, analytics labels, billing tables, and docs. + +When changing a default model, search every active default surface: runtime config, environment/config files, setup docs, tests, CLI defaults, and deployment examples. Update them together. + +For each usage site, record: + +- source model and why it appears to be used; +- endpoint and SDK/client surface; +- prompt surface; +- effective reasoning effort, including defaults; +- latency, cost, context, and quality role; +- tools, structured outputs, caching, state replay, and multimodal inputs; +- downstream parsers or user-visible contracts; +- migration class and validation plan. + +## Choose the target model by role + +Use this as a starting map, then validate against the repository's workload: + +| Existing role | Starting GPT-5.6 target | Reason | +| --- | --- | --- | +| Unsuffixed GPT-5 flagship, GPT-5.5, or GPT-5.4 flagship | `gpt-5.6-sol` | Sol is the flagship-equivalent tier. | +| Mini model, balanced lower-cost route, or medium-throughput worker | `gpt-5.6-terra` | Terra is the mini-like tier. | +| Nano model, classification, extraction, routing, high-volume, or strict-latency route | `gpt-5.6-luna` | Luna is the nano-like tier. | +| GPT-4.1 or GPT-4o latency-sensitive flow | Evaluate Luna and Terra first; use Sol only if quality requires it | A flagship replacement can change latency and cost materially. | +| Reasoning-heavy or hardest quality-first flow | Start with Sol at the old effective effort | Preserve the reasoning contract before tuning. | +| Old Pro usage | Sol plus `reasoning.mode: "pro"`, only if the user wants Pro behavior | GPT-5.6 Pro is a mode, not a separate model slug. | +| Router, fallback, or model picker | Add the family by role | Do not collapse a multi-model design into Sol. | +| Third-party or provider-specific model | Leave unchanged unless the user explicitly requests provider migration | Model-name similarity is not a safe mapping. | + +Important limits to check in live docs: + +- Sol and Terra have roughly 1.05M context and 128K maximum output. +- Luna has a smaller 400K context and 128K maximum output. +- Sol and Terra long-context requests above 272K input tokens can change pricing for the full request. + +Do not invent prices, limits, or capability flags. Fetch them from current docs before updating a registry or UI. + +For model pickers and registries, preserve existing model entries by default. Add GPT-5.6 Sol, Terra, and Luna as new options unless the user explicitly asks to replace or remove older models. Do not invent pricing, context limits, capabilities, or metadata unless confirmed from canonical docs. + +If using the `gpt-5.6` alias, record the returned `response.model` during validation. Do not assume an alias and an explicit Sol slug appear identically in dashboards, rate-limit configuration, analytics, or billing metadata. + +## Preserve effective reasoning before tuning + +GPT-5.6 supports `none`, `low`, `medium`, `high`, `xhigh`, and `max`. If omitted, GPT-5.6 defaults to `medium`. + +This is a behavioral migration hazard: + +- GPT-5.5 commonly defaulted to `medium`. +- GPT-5.4, mini, and nano usages commonly defaulted to `none`. +- A previously omitted setting can therefore become slower, more expensive, and incompatible with Chat Completions function tools after the model swap. + +For each usage: + +1. If effort is explicit, preserve it for the first 5.6 run when supported. +2. If effort is omitted and the old effective default is known, add it explicitly only when GPT-5.6's omitted default would change behavior. If both old and new omitted defaults are the same, keep it omitted. +3. If the old effective value is unknown, do not guess. Flag it and compare the old behavior with 5.6 at the likely baseline. +4. After the baseline passes, test the same setting and one lower on representative tasks. +5. Use `xhigh` or `max` only for hard quality-first workloads where evals show a meaningful gain. + +Do not globally recommend `max`. Before increasing effort, check whether the actual failure is a missing success criterion, dependency rule, tool-routing rule, state-replay bug, or validation loop. + +Use the field shape that belongs to the endpoint. + +Responses: + +```json +{ + "model": "gpt-5.6-sol", + "reasoning": { "effort": "none" } +} +``` + +Chat Completions: + +```json +{ + "model": "gpt-5.6-sol", + "reasoning_effort": "none" +} +``` + +## Chat Completions and function tools + +This is the most important endpoint-specific check. + +For GPT-5.6, function tools in Chat Completions are compatible only with effective reasoning `none`. Reasoning with tools should use the Responses API. + +Because GPT-5.6 defaults to `medium`, this combination is unsafe: + +```json +{ + "model": "gpt-5.6-luna", + "tools": [{ "type": "function", "function": { "...": "..." } }] +} +``` + +For a latency-sensitive Chat Completions flow that must keep function tools, explicitly preserve `none`: + +```json +{ + "model": "gpt-5.6-luna", + "reasoning_effort": "none", + "tools": [{ "type": "function", "function": { "...": "..." } }] +} +``` + +If the application needs both reasoning and tools: + +- migrate that flow to Responses when implementation changes are in scope; +- otherwise report it as a compatibility blocker; +- do not hide the incompatibility by removing tools, dropping required reasoning, or changing the workload's behavior without approval. + +If the live API rejects the intended `none` path, treat it as a current API compatibility issue and report the exact request and error rather than inventing a workaround. + +## Responses API and conversation state + +Prefer Responses for reasoning, tools, multi-turn agents, and new 5.6 capabilities. + +For ordinary multi-turn Responses calls, preserve the repository's existing state strategy. Do not add persisted reasoning merely because it exists. + +If deliberately enabling persisted reasoning: + +- use `reasoning.context: "all_turns"` only when the objective and assumptions remain stable; +- prefer `previous_response_id` when the server can carry state; +- when replaying manually, preserve every prior user input and every relevant output item, not only assistant text; +- with `store: false` or ZDR, request and replay `reasoning.encrypted_content`; +- use current-turn behavior when old reasoning may be stale or misleading. + +For manual replay, preserve item types, IDs, call IDs, caller metadata, and assistant phase values exactly. Incomplete replay can silently reduce quality or break tool continuation. + +## Prompt caching + +Do not assume old cache-hit behavior survives the model swap. + +GPT-5.6 implicit caching places a managed breakpoint near the latest user or tool message and no longer relies on 128-token rounding. A prompt with a large stable prefix followed by a changing suffix can therefore lose cache hits even when the stable prefix itself has not changed. + +Audit: + +- large reusable system/developer prompts; +- dynamic suffixes appended to otherwise stable prompts; +- changing timestamps, request IDs, user-specific values, or tool lists in the prefix; +- cache keys, retention settings, and cache dashboards; +- token accounting that assumes reads only and ignores writes. + +Migration rules: + +- keep reusable prefixes stable; +- do not churn large system prompts unnecessarily; +- compare old and new `cached_tokens`, `cache_write_tokens`, latency, and cost; +- use explicit cache breakpoints only when a measured workload has a stable boundary that implicit caching misses; +- do not globally convert every prompt to explicit caching; +- do not send 5.6-only cache fields to older routes in a mixed-model system. + +When old and GPT-5.6 routes share a request builder, isolate GPT-5.6-only fields instead of applying them globally. + +The new top-level request shape uses `prompt_cache_options`, for example: + +```json +{ + "prompt_cache_options": { + "mode": "explicit", + "ttl": "30m" + } +} +``` + +Place explicit breakpoints at the actual stable rendered boundary using `prompt_cache_breakpoint`. Preserve `prompt_cache_key` when the application already uses it. Treat the older `prompt_cache_retention` shape as deprecated and verify the live docs before rewriting it. + +Cache writes cost more than ordinary uncached input, so a lower hit rate can be both slower and more expensive. + +## Images, PDFs, files, and long context + +GPT-5.6 can change token and latency behavior without any prompt change: + +- for image inputs, omitted or `auto` image detail can preserve original dimensions; +- for PDF/file inputs in Responses, omitted or `input_file.detail: "auto"` can use high page-image detail; +- Chat Completions file inputs do not expose the same detail control; +- long-context Sol and Terra requests can cross pricing thresholds; +- Luna's smaller context can break workloads that fit in Sol or Terra. + +For multimodal or long-context usages: + +1. Measure input tokens and latency before and after. +2. Make detail explicit when cost or latency matters. +3. Resize images or use lower detail when the task does not need original spatial precision. +4. Keep original/high detail for dense, coordinate-sensitive, OCR, localization, or visual-inspection tasks where it materially improves quality. +5. Test worst-case context lengths, not only typical requests. + +Do not claim a capability was removed based only on a missing metadata flag. Verify against current docs and a representative request. + +## Structured outputs, parsers, and tool contracts + +Keep output contracts explicit: + +- preserve JSON schemas, required fields, enums, refusal handling, and parser expectations; +- preserve tool names, parameter schemas, call IDs, and retry behavior; +- keep citations, evidence fields, or native artifacts when downstream consumers require them; +- validate that the final answer still satisfies the contract, not merely that a tool call succeeded. + +Do not fix a failing migration by weakening a schema, deleting required behavior, removing routes, dropping tools, or changing business logic unless the user explicitly asked for that product change. + +## Optional: Pro mode + +Do not enable Pro mode during a baseline migration unless the old usage was Pro-like or the user explicitly asks for it. + +GPT-5.6 Pro uses the base model with a reasoning mode: + +```json +{ + "model": "gpt-5.6-sol", + "reasoning": { + "mode": "pro", + "effort": "medium" + } +} +``` + +Rules: + +- use Responses, not Chat Completions; +- do not search for or invent a separate `gpt-5.6-pro` slug; +- supported Pro efforts begin at `medium`; +- mode and effort are separate decisions; +- compare task quality, total latency, and actual billed token usage against standard mode. + +If migrating a legacy Pro slug, make the mode change explicit and evaluate it separately from ordinary Sol migration. + +## Optional: Programmatic Tool Calling + +Programmatic Tool Calling is not a required part of moving to GPT-5.6. Add it only when code can reduce large structured intermediate results before they return to model context. + +Good candidates: + +- bounded read-only filtering, joining, sorting, ranking, deduplication, and aggregation; +- batching many similar records; +- repeated deterministic validation; +- map-reduce style retrieval with a compact result schema. + +Poor candidates: + +- one direct tool call; +- adaptive workflows where each result changes the next decision; +- write, approval, or side-effecting flows; +- citation-heavy or native-artifact flows; +- semantic judgment that should remain visible to the model. + +Request-shape requirements: + +```json +{ + "tools": [ + { "type": "programmatic_tool_calling" }, + { + "type": "function", + "name": "lookup_records", + "allowed_callers": ["programmatic"] + } + ] +} +``` + +Do not nest `programmatic_tool_calling` under another `tools` property. When enabled, the host must handle `program`, program-issued `function_call`, `function_call_output`, and `program_output` items. Preserve the original `call_id` and `caller` when returning function results. + +Constrain the stage, eligible read-only tools, output schema, retry limit, and handoff back to direct judgment. Validate the final user-visible answer; a correct program result can still become an incorrect final answer. + +## Optional: multi-agent beta + +Do not enable multi-agent behavior during a baseline migration unless the application already has a clear parallelizable workflow and the user asks for it. + +Enabling it requires: + +- the `OpenAI-Beta: responses_multi_agent=v1` header; +- `multi_agent: { "enabled": true, "max_concurrent_subagents": 3 }`; +- handling `multi_agent_call`, `multi_agent_call_output`, and `agent_message` items; +- executing ordinary developer-defined function calls from any agent and returning all required outputs; +- preserving new items for replay and tracing; +- checking incompatibilities with compaction, reasoning summaries, and tool-call limits in current docs. + +Cap concurrency. Do not let a migration task create unbounded subagents, duplicate work, or finish without a final synthesis. + +## Prompt migration judgment + +After the model and API baseline is working, run representative traces before editing prompts. Change prompts only for measured failures. + +For GPT-5.6, prefer: + +- shorter, outcome-oriented prompts; +- explicit success criteria, dependencies, stopping conditions, and completion boundaries; +- preserved user-provided values; +- decision criteria for implicit choices instead of universal defaults or keyword maps; +- explicit autonomy and permission boundaries; +- explicit tool routing, resource links, breadcrumbs, and expected tool choice; +- staged plans, current-layer awareness, and concise handoffs for long work; +- real validation before declaring completion. + +Avoid: + +- generic `be brief`, `be thorough`, or `think step by step` instructions; +- blanket language instructions that can cause unwanted language switching; +- repeating `ask first` until safe local work becomes blocked; +- giant prompt rewrites that make the source of a regression impossible to identify; +- telling the model to minimize tool loops when correctness, evidence, or required validation needs more work. + +For coding or agentic migrations, add concrete preservation and verification rules: + +``` +Preserve existing functionality, routes, outputs, and user-visible behavior. +Do not delete or disable required behavior merely to make the build pass. +Before finishing, run the relevant build, tests, type checks, render or smoke +checks, and report the evidence. +``` + +For long-running work, define the current layer: research, design, implementation, review, or external coordination. Do not let the model silently move to another layer. + +## Upgrade workflow + +1. Fetch current live 5.6 docs and the Prompting Best Practices section. +2. Inventory every usage site and its adjacent prompt, config, registry, parser, and test surfaces. +3. Classify each usage by role and migration class. +4. Choose Sol, Terra, or Luna by the existing workload's role. +5. Preserve the old effective reasoning effort explicitly. +6. Run the compatibility gates: + - endpoint and SDK support; + - Chat Completions plus function tools; + - cache topology and cache fields; + - context length and long-context cost; + - image, PDF, and file detail; + - structured outputs and parsers; + - Responses state replay and tool continuation; + - mixed-model routing and unsupported new fields. +7. Apply the smallest safe model, config, registry, and prompt changes. +8. Do not add optional Pro, persisted reasoning, PTC, explicit caching, or multi-agent behavior unless needed and measurable. +9. Run existing tests and representative evals. +10. Report changed, unchanged, blocked, and confirmation-needed sites separately. + +## Validation matrix + +Prefer a controlled comparison: + +1. old model + old prompt + old settings; +2. GPT-5.6 target + same prompt + preserved effective reasoning; +3. GPT-5.6 target + same prompt + one lower effort; +4. GPT-5.6 target + the smallest prompt or API fix required by a measured failure; +5. optional feature treatment, isolated from the baseline. + +Measure what matters for the workflow: + +- task success and user-visible quality; +- structured-output validity and parser success; +- tool choice, tool arguments, retries, loop count, and completion rate; +- TTFT, end-to-end latency, timeout rate, and concurrency behavior; +- input, output, reasoning, cached, and cache-write tokens; +- cost per successful task; +- long-context, compaction, and replay behavior; +- image/PDF token use and visual/OCR accuracy; +- completeness, preserved behavior, citations, and validation evidence. + +For model routers and pickers, test at least one representative workload for each role. Verify that the cheapest or fastest tier is not accidentally used for quality-critical work and that Sol is not accidentally used for every workload. + +## Required final report + +Return: + +- `Current usage inventory`: each model site, endpoint, role, prompt surface, and old effective reasoning. +- `Target mapping`: Sol, Terra, Luna, unchanged, or confirmation-needed, with the reason. +- `Changes made`: model strings, reasoning settings, prompts, registries, metadata, tests, and API-shape changes. +- `Compatibility checks`: Chat Completions/tools, caching, state replay, multimodal detail, context/cost, schemas, and mixed-model routing. +- `Prompt changes`: each surgical edit and the failure mode it addresses. +- `Validation`: commands, evals, traces, before/after measurements, and remaining gaps. +- `Unchanged sites`: historical, pinned, ambiguous, or intentionally role-specific usages. +- `Blockers and open questions`: exact issue, why it is unsafe to guess, and the smallest next step. + +Never say the migration is complete merely because model strings changed. It is complete only when the affected behavior and contracts have been validated or the remaining gaps are stated explicitly. diff --git a/skills/.system/openai-docs/scripts/resolve-latest-model-info b/skills/.system/openai-docs/scripts/resolve-latest-model-info new file mode 100755 index 0000000..1190cba --- /dev/null +++ b/skills/.system/openai-docs/scripts/resolve-latest-model-info @@ -0,0 +1,31 @@ +#!/bin/sh +set -eu + +SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +SCRIPT_PATH="$SCRIPT_DIR/resolve-latest-model-info.cjs" + +if [ -n "${NODE:-}" ] && [ -x "$NODE" ]; then + "$NODE" "$SCRIPT_PATH" "$@" + exit $? +fi + +if command -v node >/dev/null 2>&1; then + node "$SCRIPT_PATH" "$@" + exit $? +fi + +for CANDIDATE in \ + "$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node" \ + "$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/bin/node" \ + "/opt/homebrew/bin/node" \ + "/usr/local/bin/node" \ + "/usr/bin/node" +do + if [ -x "$CANDIDATE" ]; then + "$CANDIDATE" "$SCRIPT_PATH" "$@" + exit $? + fi +done + +echo "No usable Node runtime found for resolve-latest-model-info.cjs" >&2 +exit 127 diff --git a/skills/.system/openai-docs/scripts/resolve-latest-model-info.js b/skills/.system/openai-docs/scripts/resolve-latest-model-info.cjs old mode 100755 new mode 100644 similarity index 82% rename from skills/.system/openai-docs/scripts/resolve-latest-model-info.js rename to skills/.system/openai-docs/scripts/resolve-latest-model-info.cjs index 1bd16ac..498e19d --- a/skills/.system/openai-docs/scripts/resolve-latest-model-info.js +++ b/skills/.system/openai-docs/scripts/resolve-latest-model-info.cjs @@ -1,5 +1,7 @@ #!/usr/bin/env node +// Keep this entrypoint CommonJS-safe when the skill is copied into a type=module repo. + const fs = require("node:fs/promises"); const path = require("node:path"); @@ -36,15 +38,31 @@ async function readSource(source) { return fs.readFile(path.resolve(source), "utf8"); } - const response = await fetch(source, { - headers: { accept: "text/markdown,text/plain,*/*" }, - }); + let lastError; + for (let attempt = 1; attempt <= 3; attempt += 1) { + try { + const response = await fetch(source, { + headers: { accept: "text/markdown,text/plain,*/*" }, + }); - if (!response.ok) { - throw new Error(`failed to fetch ${source}: ${response.status}`); + if (response.ok) { + return response.text(); + } + + lastError = new Error("failed to fetch " + source + ": " + response.status); + if (response.status < 500 && response.status !== 429) { + break; + } + } catch (error) { + lastError = error; + } + + if (attempt < 3) { + await new Promise((resolve) => setTimeout(resolve, 250 * attempt)); + } } - return response.text(); + throw lastError; } function parseIndentedInfo(lines, startIndex) {