debugging-workflows

mbruhler's avatarfrom mbruhler

Debug workflow execution issues including syntax errors, agent failures, variable problems, and execution errors. Use when workflows fail, produce unexpected results, or user asks for debugging help.

⭐191stars🔀5forks📁View on GitHub🕐Updated Dec 18, 2025
[Debugging]

When & Why to Use This Skill

The Debugging Workflows skill is a specialized diagnostic tool designed to identify, isolate, and resolve execution failures within complex orchestration sequences. It provides systematic support for fixing syntax errors, agent invocation issues, variable passing problems, and parallel execution bottlenecks, ensuring that automated agentic workflows run reliably and efficiently.

Use Cases

  • 1. Syntax Error Correction: Quickly identify and fix invalid operators (like -> or ||), bracket mismatches, and quote errors that prevent workflows from parsing or starting.
  • 2. Agent Resolution Troubleshooting: Diagnose 'Agent not found' errors by verifying agent registries, file paths, and naming conventions in the orchestration environment.
  • 3. Data Flow Validation: Resolve issues where variables are not passing correctly between agents by checking capture syntax and interpolation logic.
  • 4. Parallel Task Optimization: Debug hanging or inconsistent workflows by isolating independent tasks and identifying race conditions in concurrent execution blocks.
  • 5. Workflow Logic Isolation: Use systematic reproduction and step-by-step isolation to pinpoint the exact location of failures in long-running or multi-stage automated processes.
namedebugging-workflows
descriptionDebug workflow execution issues including syntax errors, agent failures, variable problems, and execution errors. Use when workflows fail, produce unexpected results, or user asks for debugging help.

Debugging Orchestration Workflows

I help diagnose and fix workflow execution issues using systematic debugging techniques.

When I Activate

I activate when you:

  • Experience workflow failures
  • Get syntax errors
  • Have agent execution issues
  • Variables not working as expected
  • Ask "why isn't this working?"

Common Issues

Syntax Errors

Problem: Workflow won't parse

Symptoms:

  • "Unexpected token" errors
  • "Invalid syntax" messages
  • Workflow won't start

Solutions:

  1. Check operator syntax: ->, ||, ~> (not => or &&)
  2. Verify bracket matching: [...]
  3. Check quote matching: "instruction"
  4. Validate agent names (no typos)

Agent Not Found

Problem: Agent reference doesn't resolve

Symptoms:

  • "Agent 'X' not found"
  • Execution stops at agent invocation

Solutions:

  1. Check spelling of agent name
  2. Verify temp agent file exists: temp-agents/agent-name.md
  3. Check defined agent in registry: agents/registry.json
  4. Ensure built-in agent name is correct

Variable Issues

Problem: Variables not passing correctly

Symptoms:

  • {variable} shows as literal text
  • "Variable not found" errors
  • Empty variable values

Solutions:

  1. Verify capture syntax: agent:"task":variable_name
  2. Check interpolation: "Use {variable_name}"
  3. Ensure variable set before use
  4. Check variable name spelling

Parallel Execution Failures

Problem: Parallel tasks failing or hanging

Symptoms:

  • Only some parallel tasks complete
  • Workflow hangs at parallel section
  • Inconsistent results

Solutions:

  1. Ensure tasks are independent (no shared state)
  2. Check syntax: [task1 || task2 || task3]
  3. Verify each task can run standalone
  4. Check for race conditions

Checkpoint Issues

Problem: Checkpoints not triggering

Symptoms:

  • Checkpoints skipped
  • No user prompt shown
  • Workflow continues without pause

Solutions:

  1. Check checkpoint syntax: @checkpoint-name
  2. Verify not in auto-mode
  3. Ensure checkpoint is reachable in flow

Debugging Process

1. Reproduce

Run workflow with minimal changes to reproduce issue.

2. Isolate

Simplify workflow to find problematic section:

# If this fails:
step1 -> step2 -> step3 -> step4

# Try:
step1 -> step2  # Works?
step3 -> step4  # Works?

3. Inspect

Check execution logs for error details.

4. Fix

Apply targeted fix based on findings.

5. Verify

Run full workflow to ensure fix works.

Error Messages Guide

Error Meaning Fix
"Unexpected token" Syntax error Check syntax around error location
"Agent not found" Missing agent Verify agent exists and spelling
"Variable not found" Variable undefined Check variable was captured
"Condition failed" Condition not met Check condition logic
"Execution timeout" Task took too long Add timeout handling or simplify task

Best Practices

✅ DO:

  • Start with simple workflow, add complexity gradually
  • Test each section independently
  • Use meaningful variable names
  • Add error handling paths
  • Capture outputs for debugging

❌ DON'T:

  • Create overly complex workflows initially
  • Skip testing individual steps
  • Use cryptic variable names
  • Ignore error messages
  • Remove error handling

Diagnostic Commands

# Check temp agents exist
ls temp-agents/

# Verify agent registry
cat agents/registry.json

# Check workflow syntax file
cat examples/workflow-name.flow
  • creating-workflows: Create well-structured workflows
  • executing-workflows: Execute with better error visibility
  • managing-agents: Debug agent-related issues

Workflow not working? Show me the error and I'll help debug!