用途：当 Speakeasy SDK 生成失败或出现构建错误时，诊断失败根因并确定修复策略。触发场景包括 speakeasy run 报错、SDK 生成结果异常，或用户提出“generation failed”“SDK build error”等问题。
输入：OpenAPI 规范路径为必需；失败运行的错误输出为可选但有用信息。
输出：失败根因诊断、修复策略（overlay、改规范或用户决策）以及可执行的具体步骤。
诊断流程：先运行 lint 获取详细错误：speakeasy lint openapi --non-interactive -s <spec-path>。再将问题分类：可用 overlay 修复（缺少描述、operationId 不佳）；需修改规范（无效 schema、缺少必填字段）；需用户输入（设计决策、认证设置）。
决策框架：缺少 operationId 用 overlay，可用 speakeasy suggest operation-ids；缺少 description 通过 overlay 添加；无效 $ref、循环引用、缺少 security 需询问用户。
注意事项：不要为隐藏错误而禁用 lint 规则；不要逐个修复所有问题；不要在未询问的情况下修改源规范；不要假设能修复结构性问题。
排查树涵盖：运行时 ResponseValidationError（用契约测试识别不匹配）；SDK 与线上 API 行为不符（可能规范漂移，或第三方规范不准确，需契约测试验证）；生成 SDK 中的类型不匹配（编译期检查 schema，运行期需契约测试）；枚举值未识别（补充缺失值或使用开放枚举）。
处理大型规范可用 yq 或 jq 查看，例如 yq '.paths | keys' spec.yaml、yq '.components.schemas | keys' spec.yaml。
复杂问题可输出分析文档，列出阻塞问题、可修复问题与推荐方案。相关技能：manage-openapi-overlays、setup-sdk-testing、writing-openapi-specs。