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