mbruhler/claude-orchestration/debugging-workflows

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

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

Related Skills

• 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!