Skip to content

trycompai/comp / .agents/skills/diagnose-generation-failure

diagnose-generation-failure

Unverified

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"

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

InputRequiredDescription
OpenAPI specYesPath to spec that failed generation
Error outputHelpfulError messages from failed run

Outputs

OutputDescription
DiagnosisRoot cause of failure
Fix strategyOverlay vs spec fix vs user decision
Action itemsSpecific 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 TypeFix StrategyExample
Missing operationIdOverlayUse speakeasy suggest operation-ids
Missing descriptionOverlayAdd via overlay
Invalid $refAsk userBroken reference needs spec fix
Circular referenceAsk userDesign decision needed
Missing securityAsk userAuth 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
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall