用途：当 SDK 生成失败或出现错误时，诊断根本原因并确定修复策略。触发场景包括 speakeasy run 运行失败、SDK 生成结果异常、SDK 构建报错、工作流失败、步骤失败等。
输入：OpenAPI 规范（必需，为生成失败的规范路径）；错误输出（可选，来自失败运行的错误信息）。
输出：诊断（失败根因）、修复策略（overlay 修复、规范修复或需用户决策）、行动项（具体解决步骤）。
诊断步骤：先运行 lint 获取详细错误：speakeasy lint openapi --non-interactive -s <spec-path>。然后分类问题：可用 overlay 修复（缺少描述、operationId 不佳）；需修复规范（无效 schema、缺少必填字段）；需用户输入（设计决策、认证配置）。决策框架示例：缺少 operationId 用 overlay，可用 speakeasy suggest operation-ids；缺少描述用 overlay 补充；无效 $ref、循环引用、缺少 security 需询问用户。
禁忌：不要禁用 lint 规则掩盖错误；不要逐条修复所有问题；不要未经询问修改源规范；不要假设自己能修复结构性问题。
排障树：运行时出现 ResponseValidationError 说明 SDK 类型与服务器响应不匹配，可运行契约测试定位差异，再修规范或建 overlay 修正类型；SDK 与实际 API 行为不符可能因规范漂移或第三方规范不准，需用契约测试检测；生成 SDK 的类型不匹配，编译时报错检查规范 schema 定义，运行时则需契约测试；枚举值无法识别时，可将缺失值加入规范/overlay，或使用开放式枚举增强抗脆弱性。
处理大型 OpenAPI 规范可用 yq（YAML）或 jq（JSON）检查，例如 yq '.paths | keys' spec.yaml、yq '.paths["/users/{id}"]' spec.yaml、yq '.components.schemas | keys' spec.yaml、yq '[.paths[][].operationId // empty] | unique' spec.yaml。复杂问题可产出策略文档，分阻塞问题（需用户输入）、可修复问题（可用 overlay）和推荐方案。相关技能：manage-openapi-overlays、setup-sdk-testing、writing-openapi-specs。