diagnose-generation-failure

name	diagnose-generation-failure
description	Use when SDK generation failed or seeing errors. Triggers on "generation failed", "speakeasy run failed", "SDK build error", "workflow failed", "Step Failed", "why did generation fail"
license	Apache-2.0

diagnose-generation-failure

When SDK generation fails, diagnose the root cause and determine the fix strategy.

When to Use

• speakeasy run failed with errors
• SDK generation produced unexpected results
• User says: "generation failed", "SDK build error", "why did generation fail"

Inputs

Input	Required	Description
OpenAPI spec	Yes	Path to spec that failed generation
Error output	Helpful	Error messages from failed run

Outputs

Output	Description
Diagnosis	Root cause of failure
Fix strategy	Overlay vs spec fix vs user decision
Action items	Specific steps to resolve

Diagnosis Steps

1. Run lint to get detailed errors:

   speakeasy lint openapi --non-interactive -s <spec-path>
   

2. Categorize issues:

   • Fixable with overlays: Missing descriptions, poor operation IDs
   • Requires spec fix: Invalid schema, missing required fields
   • Requires user input: Design decisions, authentication setup

Decision Framework

Issue Type	Fix Strategy	Example
Missing operationId	Overlay	Use speakeasy suggest operation-ids
Missing description	Overlay	Add via overlay
Invalid $ref	Ask user	Broken reference needs spec fix
Circular reference	Ask user	Design decision needed
Missing security	Ask user	Auth design needed

What NOT to Do

• Do NOT disable lint rules to hide errors
• Do NOT try to fix every issue one-by-one
• Do NOT modify source spec without asking
• Do NOT assume you can fix structural problems

Strategy Document

For complex issues, produce a document:

## OpenAPI Spec Analysis

### Blocking Issues (require user input)
- [List issues that need human decision]

### Fixable Issues (can use overlays)
- [List issues with proposed overlay fixes]

### Recommended Approach
[Your recommendation]