agent-workflow-debugger

name	agent-workflow-debugger
description	Inspect, debug, and improve Open Agent Workflow runs and harnesses. Use when a workflow run looks wrong, the console visualization is confusing, agents fail or cache unexpectedly, artifacts/events need investigation, or a `.workflow.js` harness needs to be made more reliable after a run.

Agent Workflow Debugger

Use this skill to understand a workflow run from durable evidence, then make targeted fixes to the harness, runtime, adapter, or console.

Triage Order

1. Identify the run ID, adapter, status, harness, and run directory.
2. Inspect the console route /runs/<runId> when the local app is running.
3. Read durable evidence when needed:
   • events.jsonl for ordered runtime and adapter events.
   • journal.jsonl for cache/replay records.
   • artifacts/ for emitted evidence.
   • summary.json for final status and paths.
4. Compare actual phases against ctx.phase(...) calls in the source harness.
5. Decide whether the problem is authoring, adapter behavior, runtime behavior, cache/replay, or console presentation.

Debugging Heuristics

• If the console shows weird phases, inspect runtime phase events, not only meta.phases.
• If an agent lane is missing, look for task_started, task_completed, task_failed, or task_cached.
• If cache behavior is surprising, compare promptHash, stepKey, and journal.jsonl.
• If final output is weak, inspect whether the harness persisted artifacts and used a synthesis/verifier phase.
• If the graph or trace is confusing, improve the run projection or console component only after confirming the raw event data is correct.
• If a worker failed, preserve the raw adapter event before simplifying the report.

Fix Rules

Make the smallest fix at the owning layer:

• Harness prompt/phase/label problem -> edit the workflow file.
• Event parsing or product summary problem -> edit packages/server.
• Execution primitive problem -> edit packages/runtime.
• Provider-specific stream mapping problem -> edit packages/adapters.
• Presentation problem -> edit apps/console.

Do not paper over runtime or adapter issues in the console. The console should consume the run API, not infer from local runtime files directly.

Verification

After a fix, rerun the smallest meaningful path:

node --run typecheck
node --run validate
node --run console:build

For a specific workflow:

node --run build
node packages/cli/dist/bin.js run dist/examples/<workflow>.workflow.js --adapter mock --ui-exit-on-complete

When the user cares about the UI, keep or start the console and verify in the browser.

Report Shape

When reporting findings, separate:

• observed evidence
• root cause or best current theory
• files changed
• verification run
• remaining risk

Avoid dumping full event files. Quote only short relevant event snippets or summarize counts.

References

Read references/run-evidence.md when investigating event files, cache replay, or console projections.