diagnose-generation-failure Skill

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

Run lint to get detailed errors:

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

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

Troubleshooting Tree

PROBLEM
  │
  ├─ ResponseValidationError at runtime?
  │    └─ SDK types don't match server responses
  │         ├─ Run contract tests to identify mismatches
  │         └─ Fix spec or create overlay to correct types
  │
  ├─ SDK doesn't match live API behavior?
  │    ├─ Spec may have drifted from API
  │    │    → Run contract tests to detect drift
  │    └─ Third-party spec may be inaccurate
  │         → Validate with contract testing before trusting
  │
  ├─ Type mismatch errors in generated SDK?
  │    ├─ At compile time → Check spec schema definitions
  │    └─ At runtime → Server returns unexpected types
  │                    → Contract testing required
  │
  └─ Enum value not recognized?
       └─ API returned value not in spec enum
            ├─ Add missing value to spec/overlay
            └─ Or use open enums for anti-fragility

Working with Large OpenAPI Specs

Use yq (YAML) or jq (JSON) to inspect specs without loading full content:

# List all paths
yq '.paths | keys' spec.yaml

# Inspect a specific endpoint
yq '.paths["/users/{id}"]' spec.yaml

# List all schema names
yq '.components.schemas | keys' spec.yaml

# List all operationIds
yq '[.paths[][].operationId // empty] | unique' spec.yaml

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]

Related Skills

manage-openapi-overlays - Fix issues with overlays
setup-sdk-testing - Contract testing for validation
writing-openapi-specs - Spec design best practices

Agent Skills: diagnose-generation-failure

Install this agent skill to your local

Skill Files