Add freshness check for GPT-5.4 upgrade guidance

skills/.system/openai-docs/SKILL.md

@@ -1,19 +1,22 @@
 ---
 name: "openai-docs"
-description: "Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations, help choosing the latest model for a use case, or explicit GPT-5.4 upgrade and prompt-upgrade guidance; prioritize OpenAI docs MCP tools, use bundled references only as helper context, and restrict any fallback browsing to official OpenAI domains."
+description: "Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; prioritize OpenAI docs MCP tools, use bundled references only as helper context, and restrict any fallback browsing to official OpenAI domains."
 ---
 
 
 # OpenAI Docs
 
-Provide authoritative, current guidance from OpenAI developer docs using the developers.openai.com MCP server. Always prioritize the developer docs MCP tools over web.run for OpenAI-related questions. This skill may also load targeted files from `references/` for model-selection and GPT-5.4-specific requests, but current OpenAI docs remain authoritative. Only if the MCP server is installed and returns no meaningful results should you fall back to web search.
+Provide authoritative, current guidance from OpenAI developer docs using the developers.openai.com MCP server. Always prioritize the developer docs MCP tools over web.run for OpenAI-related questions. This skill may also load targeted files from `references/` for model-selection, model-upgrade, and prompt-upgrade requests, but current OpenAI docs remain authoritative. Only if the MCP server is installed and returns no meaningful results should you fall back to web search.
 
 ## Quick start
 
 - Use `mcp__openaiDeveloperDocs__search_openai_docs` to find the most relevant doc pages.
 - Use `mcp__openaiDeveloperDocs__fetch_openai_doc` to pull exact sections and quote/paraphrase accurately.
 - Use `mcp__openaiDeveloperDocs__list_openai_docs` only when you need to browse or discover pages without a clear query.
-- Load only the relevant file from `references/` when the question is about model selection or a GPT-5.4 upgrade.
+- 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` from this skill directory when the script is present, then follow `references/upgrade-guide.md` unless the resolver returns newer guidance for a dynamic latest/current/default request.
+- 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.
 
 ## OpenAI product snapshots
 
@@ -37,29 +40,39 @@ If MCP tools fail or no OpenAI docs resources are available:
 
 ## Workflow
 
-1. Clarify the product scope and whether the request is general docs lookup, model selection, a GPT-5.4 upgrade, or a GPT-5.4 prompt upgrade.
-2. If it is a model-selection request, load `references/latest-model.md`.
-3. If it is an explicit GPT-5.4 upgrade request, load `references/upgrading-to-gpt-5p4.md`.
-4. If the upgrade may require prompt changes, or the workflow is research-heavy, tool-heavy, coding-oriented, multi-agent, or long-running, also load `references/gpt-5p4-prompting-guide.md`.
-5. Search docs with a precise query.
-6. Fetch the best page and the exact section needed (use `anchor` when possible).
-7. For GPT-5.4 upgrade reviews, always make the per-usage-site output explicit: target model, starting reasoning recommendation, `phase` assessment when relevant, prompt blocks, and compatibility status.
-8. Answer with concise guidance and cite the doc source, using the reference files only as helper context.
+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 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 explicit named-model requests, preserve the requested model target and do not silently retarget to the latest model. 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.
+   - If remote docs are unavailable, use bundled fallback references and say that fallback guidance was used.
+3. For model upgrades, keep changes narrow: update active OpenAI API model defaults and directly related prompts only when safe.
+4. 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.
+5. Do not perform SDK, tooling, IDE, plugin, shell, auth, or provider-environment migrations as part of a model-and-prompt upgrade.
+6. 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. For general docs lookup, search docs with a precise query, fetch the best page and exact section needed, and answer with concise citations.
 
 ## Reference map
 
 Read only what you need:
 
-- `references/latest-model.md` -> model-selection and "best/latest/current model" questions; verify every recommendation against current OpenAI docs before answering.
-- `references/upgrading-to-gpt-5p4.md` -> only for explicit GPT-5.4 upgrade and upgrade-planning requests; verify the checklist and compatibility guidance against current OpenAI docs before answering.
-- `references/gpt-5p4-prompting-guide.md` -> prompt rewrites and prompt-behavior upgrades for GPT-5.4; verify prompting guidance against current OpenAI docs before answering.
+- `https://developers.openai.com/api/docs/guides/latest-model.md` -> current model-selection and "best/latest/current model" questions.
+- `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.
 
 ## Quality rules
 
 - Treat OpenAI docs as the source of truth; avoid speculation.
+- Keep migration changes narrow and behavior-preserving.
+- Prefer prompt-only upgrades when possible.
+- Do not invent pricing, availability, parameters, API changes, or breaking changes.
 - Keep quotes short and within policy limits; prefer paraphrase with citations.
 - If multiple pages differ, call out the difference and cite both.
-- Reference files are convenience guides only; for volatile guidance such as recommended models, upgrade instructions, or prompting advice, current OpenAI docs always win.
+- If official docs and repo behavior disagree, state the conflict and stop before making broad edits.
 - If docs do not cover the user’s need, say so and offer next steps.
 
 ## Tooling notes