Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Debug Output SDK workflow issues. Use when user reports a workflow failing, erroring, hanging, producing wrong results, or asks to debug, troubleshoot, or investigate a workflow execution.
.claude/skills/growthxai-output-debug-workflow/SKILL.md| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-07 | ✗→✓ | ▲ Improved | 60% | 0% |
| case-09 | ✗→✓ | ▲ Improved | 42% | 0% |
| case-21 | ✗→✓ | ▲ Improved | 46% | 0% |
| case-03 | ✓→✗ | ▼ Worse | -24% | 0% |
| case-05 | ✓→✗ | ▼ Worse | 92% | 0% |
Your task is to systematically debug an Output SDK workflow issue in a local development environment.
The arguments the user provided describe the problem they're experiencing, and may include a specific workflow ID.
Use the todo tool to track your progress through the debugging process.
Follow a systematic approach to identify and resolve workflow execution issues: verify infrastructure, gather evidence, analyze traces, and apply targeted fixes.
<pre_flight_check> EXECUTE: Claude Skill: output-meta-pre-flight </pre_flight_check>
<process_flow>
<step number="1" name="verify_services">
Before debugging, confirm that all required services are operational. The output-services-check skill provides comprehensive guidance.
<verification_commands>
bash# Check Docker containers are running docker ps | grep output # Verify Output services respond curl -s http://localhost:3001/health || echo "API not responding" # Check Temporal UI is accessible curl -s http://localhost:8080 > /dev/null && echo "Temporal UI accessible" || echo "Temporal UI not accessible"
</verification_commands>
<decision_tree> IF docker_not_running: RUN: docker compose up -d WAIT: for services to start (30-60 seconds) IF output_dev_not_running: RUN: npx output dev WAIT: for services to initialize IF all_services_running: PROCEED: to step 2 </decision_tree>
Expected State:
output are runninghttp://localhost:3001http://localhost:8080</step>
<step number="2" name="list_workflow_runs">
Identify the failing workflow execution by listing recent runs. The output-workflow-runs-list skill provides detailed filtering guidance.
<list_commands>
bash# List all recent workflow runs npx output workflow runs list # Filter by specific workflow type (if known) npx output workflow runs list <workflowName> # Get detailed JSON output for analysis npx output workflow runs list --json # Limit results to most recent npx output workflow runs list --limit 10
</list_commands>
<identification_criteria> Look for:
</identification_criteria>
<decision_tree> IF user_provided_workflow_id: USE: provided workflow ID PROCEED: to step 3 IF failed_runs_found: SELECT: most recent failed run NOTE: workflow ID from output PROCEED: to step 3 IF no_runs_found: CHECK: workflow exists with npx output workflow list IF workflow_not_found: REPORT: workflow doesn't exist SUGGEST: verify workflow name and location ELSE: SUGGEST: run the workflow with npx output workflow run <name> </decision_tree>
</step>
<step number="3" name="debug_workflow" subagent="workflow-debugger">
Retrieve and analyze the execution trace for the identified workflow. The output-workflow-trace skill provides analysis techniques.
<debug_commands>
bash# Display execution trace (text format) npx output workflow debug <workflowId> # Display full untruncated trace (JSON format) - recommended for detailed analysis npx output workflow debug <workflowId> --json
</debug_commands>
Tip: Use --json for complete trace data without truncation.
<analysis_checklist>
</analysis_checklist>
<temporal_ui_guidance> For visual workflow inspection, open the Temporal Web UI at http://localhost:8080:
</temporal_ui_guidance>
</step>
<step number="4" name="suggest_fixes" subagent="workflow-quality">
Based on the trace analysis, identify the error pattern and suggest targeted fixes. Claude will invoke the relevant error skill based on symptoms.
<error_matching>
| Symptom | Skill | |---------|-------| | "incompatible schema" errors, type errors | output-error-zod-import | | Replay failures, inconsistent results | output-error-nondeterminism | | Retries not working, errors swallowed | output-error-try-catch | | Type errors, undefined properties at step boundaries | output-error-missing-schemas | | Workflow hangs, determinism errors | output-error-direct-io | | Untraced requests, axios errors | output-error-http-client |
</error_matching>
<decision_tree> IF error_matches_known_pattern: INVOKE: relevant error skill for detailed fix ELSE: CONSULT: workflow-quality subagent for additional patterns SUGGEST: Manual trace inspection in Temporal UI </decision_tree>
<verification> After applying fix:
bash# Re-run the workflow to verify npx output workflow run <workflowName> --input '<json>' # Or start asynchronously and check result npx output workflow start <workflowName> --input '<json>' npx output workflow status <workflowId> npx output workflow result <workflowId> # Or, if the fix only affects a specific step and earlier steps succeeded, # re-run from after the last known-good step (skips re-executing earlier work) npx output workflow reset <workflowId> --step <lastGoodStep> --reason "<fix description>"
For targeted rerun after fixing a downstream step, see the output-workflow-reset skill. </verification>
</step>
</process_flow>
<post_flight_check> EXECUTE: Claude Skill: output-meta-post-flight </post_flight_check>
---- START ----
Use the problem description and any optional workflow ID the user provided.
| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-11 | fail→fail | 18,512 | 9,524 | -49% | 1 | 1 | 0% | 783 | 2,163 | +176% | 0 | 0 | — |
case-17 | fail→fail | 21,818 | 7,927 | -64% | 1 | 1 | 0% | 1,059 | 1,793 | +69% | 0 | 0 | — |
case-18 | fail→fail | 19,808 | 7,371 | -63% | 1 | 1 | 0% | 1,100 | 1,922 | +75% | 0 | 0 | — |
case-01 | fail→fail | 17,886 | 6,606 | -63% | 1 | 1 | 0% | 1,893 | 1,750 | -8% | 0 | 0 | — |
case-02 | fail→fail | 4,259 | 7,236 | +70% | 1 | 1 | 0% | 164 | 1,833 | +1018% | 0 | 0 | — |
case-03 | pass→fail | 15,066 | 8,160 | -46% | 1 | 1 | 0% | 2,295 | 1,740 | -24% | 0 | 0 | — |
case-04 | fail→fail | 8,300 | 13,274 | +60% | 1 | 1 | 0% | 1,400 | 1,884 | +35% | 0 | 0 | — |
case-05 | pass→fail | 12,434 | 6,992 | -44% | 1 | 1 | 0% | 944 | 1,811 | +92% | 0 | 0 | — |
case-06 | fail→fail | 5,747 | 6,759 | +18% | 1 | 1 | 0% | 902 | 1,901 | +111% | 0 | 0 | — |
case-07 | fail→pass | 9,667 | 5,226 | -46% | 1 | 1 | 0% | 1,460 | 2,333 | +60% | 0 | 0 | — |
case-08 | fail→fail | 8,331 | 12,725 | +53% | 1 | 1 | 0% | 1,416 | 2,718 | +92% | 0 | 0 | — |
case-09 | fail→pass | 10,560 | 9,414 | -11% | 1 | 1 | 0% | 1,761 | 2,497 | +42% | 0 | 0 | — |
case-10 | fail→fail | 14,390 | 7,701 | -46% | 1 | 1 | 0% | 2,089 | 2,261 | +8% | 0 | 0 | — |
case-12 | fail→fail | 12,140 | 7,620 | -37% | 1 | 1 | 0% | 1,700 | 1,850 | +9% | 0 | 0 | — |
case-13 | pass→pass | 13,224 | 11,561 | -13% | 1 | 1 | 0% | 1,942 | 3,443 | +77% | 0 | 0 | — |
case-14 | fail→fail | 13,549 | 34,356 | +154% | 1 | 1 | 0% | 2,468 | 4,561 | +85% | 0 | 0 | — |
case-15 | fail→fail | 10,787 | 8,440 | -22% | 1 | 1 | 0% | 1,936 | 2,001 | +3% | 0 | 0 | — |
case-16 | fail→fail | 6,124 | 8,552 | +40% | 1 | 1 | 0% | 1,104 | 1,809 | +64% | 0 | 0 | — |
case-19 | pass→fail | 8,480 | 8,615 | +2% | 1 | 1 | 0% | 1,370 | 1,832 | +34% | 0 | 0 | — |
case-20 | pass→pass | 19,731 | 19,825 | +0% | 1 | 1 | 0% | 3,687 | 5,320 | +44% | 0 | 0 | — |
case-21 | fail→pass | 23,024 | 24,381 | +6% | 1 | 1 | 0% | 4,107 | 5,982 | +46% | 0 | 0 | — |
case-22 | pass→pass | 7,491 | 10,085 | +35% | 1 | 1 | 0% | 1,442 | 3,292 | +128% | 0 | 0 | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted, and 6 counted toward the lift figure. The other 16 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of 0 percentage points is the difference between those two pass rates over the 6 comparable cases. 4 cases got worse with the skill loaded, and they are included in that figure.
Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.
Other measured skills in the registry, with their headline benchmark lift.