speakeasy-api/agent-skills/diagnose-generation-failure

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

# 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

## 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]