debugging-workflows

name	debugging-workflows
description	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.

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

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!