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-