Debugging Playbook
Operational guide for inspecting execution state and debugging workflows.CLI Commands
Inspecting State
View Phase Progress
View Step Progress
View Running Tasks
View State History
Claude Code Logs
Claude execution logs are stored at:session.jsonl- Full conversation logmetadata.json- Session metadata
Correlating Logs to Executions
Common Issues
Workflow Stalls
Symptom: Orchestration stops advancing. Causes:- No state change in
onFinishedcallback - Untracked async work completing after task check
- Missing task completion call
Phase Not Advancing
Symptom: Phase stuck, next phase never starts. Causes:- Step not completing
- No Steps in Phase (see Phase docs)
skipIfreturning wrong value
Crash Recovery Not Working
Symptom: Workflow restarts from beginning. Causes:- Using
useStateinstead of SQLite state - Not checking
db.execution.findIncomplete() - Database not persisted (in-memory mode)
db.state and execution resume logic is present:
Database Schema
Key tables for debugging:| Table | Purpose |
|---|---|
executions | Workflow run records |
state | Key-value state storage |
phases | Phase progress tracking |
steps | Step completion tracking |
tasks | Async task tracking |
agents | Agent execution logs |