/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!**