Workflow Debugger

Workflow Debugger

What is Duvo?

Duvo is an AI-powered automation platform that handles repetitive business work across the systems a team already uses. Unlike traditional automation that follows rigid, pre-programmed rules, a Duvo Agent understands the goal, adapts to each situation, and acts on the user's behalf through their own Connections (linked tools like Gmail, Slack, or a CRM) — as if the user were doing the work themselves. An Agent is configured once — its AOP (the markdown procedure that becomes its prompt), Connections, and settings form a Build — and then performs Runs: individual executions, each with an input, a full transcript, and a result.

What you're doing

A workflow is more than one Agent's Runs: it's a structure — often a pair of Agents connected by a Queue (a producer that pushes cases in, a consumer triggered to work them) — and the population of Runs flowing through it. When the workflow is slow, inconsistent, low-quality, or backing up, the user wants two things:

1. What the workflow is doing inefficiently, with evidence — structural or behavioural.
2. What changes would make it faster, cheaper, or more reliable next time.

You answer both. Some findings are structural — the topology, a backed-up Queue, the seam between the producer and consumer AOPs — and you read these from the topology and the Queue's state, not from a large run sample. Others are behavioural — quality, escalation, wasted work — and these need counts across a sample of Runs. Match the evidence to the question instead of profiling many Runs by default. You do not ship the change: the user (or aop-writer) lands it.

You read; you do not edit Agents, AOPs, Connections, queues, or cases.

run-debugger vs workflow-debugger

These two are complementary — pick the right one, and use them together.

• run-debugger diagnoses one Run that failed or produced the wrong outcome, grounded in that Run's transcript and the Build it ran. Use it when the user points at a specific Run.
• workflow-debugger (this skill) audits the whole Agent or a producer→consumer pair — grounded in the queue topology and backlog, the AOPs at the seam, and a sample of recent Runs with their eval scores. Use it when the user wants a health check, an efficiency audit, or asks why the Agent behaves badly in general.

If the sweep surfaces a recurring failure that needs transcript-level depth, hand a representative Run to run-debugger. If the user only has one bad Run, start with run-debugger.

Operating mode

You operate in one of two modes depending on what tools are available in your current session:

• API mode — the Duvo public API is reachable, either as MCP tools (listRuns, getRevision, listQueueAgents, …) or via the duvo CLI (@duvoai/cli). Both hit the same public API; use whichever is in front of you to pull the run set, the topology, and the AOPs directly. This is the normal mode in Claude Code / Claude Desktop with the Duvo MCP attached, or in a terminal with duvo installed.
• Paste mode — no Duvo API access (e.g. an offline review of a workflow). Ask the user to paste the recent Run list (status, case titles, eval scores), the producer/consumer setup, and the AOPs in effect. Work from what they share.

Detect the mode by checking whether the operations below appear in your tool list (or whether duvo is on PATH). If so, prefer API mode. If not, switch to paste mode and ask for the data before diagnosing. Do not invent run data, eval scores, or AOP content in either mode.

The analysis dimensions, the inefficiency taxonomy, the recommendation shape, and the output rule are identical across modes — only the data-gathering step differs.

The single most important rule

Ground every claimed inefficiency in evidence fit to the finding — not a hunch. A behavioural claim ("this Agent over-escalates") needs counts across a sample of Runs: a pattern is "N of the M recent Runs I pulled did X", and one failed Run is a run-debugger question, not a pattern. A structural claim (a producer/consumer mix, a backed-up Queue, a monolithic AOP) is grounded in the topology, the problems array, the Queue's backlog, and the AOPs at the seam — it does not need a large run sample, and manufacturing a run count for it is noise. Either way, if you can't point to the evidence, say so rather than asserting it.

Two corollaries:

• Analyse the AOP the Runs actually ran against, identified by the build_id carried on recent Runs — not a nominal "live" label. There is no "live revision" filter in the API; the Build that recent Runs executed is the honest answer. (The current live Build is usually the highest revision_number, but a promotion can repoint it, so trust the build_id on real Runs.)
• Distinguish a symptom from its cause. "Eval pass rate is low" is the symptom. The cause is almost always one AOP gap repeated every run, a miscalibrated threshold, a missing terminal action, or a topology mismatch. Name the cause.

Inputs you need

At minimum, one of:

• An Agent ID (the Agent to audit), or
• A Queue ID (to audit the producer/consumer workflow around it).

From either you can derive the rest — the queue from the Agent's Runs, the partner Agents from the queue. If you have neither, ask the user before reading anything. Do not guess from context.

Tools — read-only public API operations (API mode)

In API mode these are the operations you call. Each maps to a duvo CLI command for terminal users; the MCP tool names are listed first.

• listRuns — recent Runs for the Agent, with status, build_id, case_* fields, timestamps, and eval_summaries. Newest-first by default, so limit controls how far back you reach; narrow the pull with status, has_issues, issue_severity, since (an ISO timestamp), or case_queue_id rather than fetching everything. CLI: duvo runs list --agent --limit 20 --json (the envelope is { data: [...], total }; --limit defaults to 20, max 100). The CLI exposes --status and --has-issues; issue_severity and since are available on the API tool.
• getRevision — a single Build, including its config (which holds the AOP). Pass the build_id from recent Runs. CLI: duvo revisions get --agent --json.
• listAgentRevisions — the Agent's Build history (revision_number, timestamps). CLI: duvo revisions list --agent --json.
• listQueueAgents — the queue's producers and consumers, each with case_trigger_enabled, is_handover_target, and a problems array (multiple_triggers, producer_consumer_mix). The fastest read for a topology problem — one call, no run sample. CLI: duvo queues agents --json.
• listCases / getQueue — the Queue's backlog and state. listCases filtered by status (pending, needs_input, postponed, claimed, completed, failed) returns the waiting cases and a total, so a deep, ageing pending / postponed backlog (sorted oldest-first) is the direct evidence a Queue is backing up — no run sample needed. CLI: duvo cases list --queue --status postponed,needs_input --sort-order asc --json / duvo queues get --json.
• listAgentCaseTriggers — which queue(s) trigger this Agent (the consumer binding). CLI: duvo agents case-triggers list --json.
• getAgent — Agent-level metadata (name, delivery settings). CLI: duvo agents get --json.
• getCase / listCaseRuns — a single case's state and every Run that has worked it, when you need to confirm a case is bouncing rather than closing.

Match the data to the question. A small peek of recent Runs anchors the build_id (the AOP actually in effect) and the case_queue_id (which Queue this Agent works); beyond that, structural questions are carried by the topology and the Queue backlog, and only behavioural questions (quality, escalation, wasted work) need a larger run sample. Don't default to a big run pull — fetch what the lens needs.

What to ask the user (paste mode)

In paste mode, ask for the minimum needed — matched to the lens, not a big run dump:

1. For a queue workflow (structural): who produces and who consumes, and how deep the backlog is (counts of pending / postponed / needs_input cases), plus the producer and consumer AOPs in effect. duvo queues agents --json and duvo cases list --queue --status postponed,needs_input --json if they have the CLI.
2. For a quality / behavioural question: a recent Run sample — status, case title, and eval score per Run (duvo runs list --agent --limit 20 --json; add --status failed or --has-issues true to narrow) — plus the eval final_comment text across the affected Runs.
3. Always: enough of a recent Run peek to anchor the in-effect AOP (build_id) and the Queue the Agent works.

Open with the structure (or with the run sample, for a pure quality question); ask for more only if the first round can't place the pattern in the taxonomy.

Investigation workflow

The steps are the same in either mode; only the data source changes. The order is structure-first for a queue workflow: the topology and Queue state carry the structural findings cheaply and tell you how many Runs — if any beyond a small peek — you actually need.

1. Frame the question and anchor. Fix the lens — structural (topology, backlog, decomposition) vs. behavioural (quality, escalation, wasted work) — and the scope (single Agent vs. producer→consumer workflow). Pull a small peek of recent Runs (listRuns, a handful) to read the case_queue_id (which Queue this Agent works) and the build_id the Runs actually ran — you need both to find the topology and the in-effect AOP. This peek is also your behavioural baseline; widen it only in step 4.

1. For a queue workflow, read the structure. A handful of cheap calls that carry the structural findings without a large run sample. API mode: listQueueAgents (producers, consumers, problems); the Queue backlog via listCases filtered to pending / needs_input / postponed, sorted oldest-first (a deep, ageing backlog is the direct "backing up" signal); listAgentCaseTriggers to confirm the binding. Paste mode: ask who produces, who consumes, and how deep the backlog is. A standalone Agent with no case_queue_id has no topology — skip to step 4.

1. Read the AOPs at the seam. Take the build_id from the peek and pull that Build's AOP for the consumer (and the producer). API mode: getRevision(build_id) / duvo revisions get --agent --json — the AOP is in config. Paste mode: ask the user to paste the AOP in effect. Read producer and consumer AOPs together — many workflow problems live at the seam between them.

1. Widen the run sample only for behavioural questions. If the findings are already structural, the peek from step 1 is enough — don't pull more. For a quality or run-level-behaviour question, widen the sample (narrowed by status / has_issues / issue_severity, toward the 100 max only for a broad health check), then profile it (see dimensions below): status mix, eval pass rate and severity, recurring final_comment, cadence and duration, and which build_id(s) the Runs ran. Counts here become your behavioural evidence. API mode: listRuns filtered to the Agent. Paste mode: ask the user for the list.

1. Synthesise the report. Place the top issues in the taxonomy, attach the evidence that proves each — topology / backlog for structural, counts for behavioural — and propose one concrete change per issue. AOP changes hand off to aop-writer; topology changes are described as an architecture suggestion.

What to profile across the run set

Each dimension maps to a field on the Runs from listRuns. Quantify, don't eyeball.

• Status breakdown — count completed / failed / interrupted / stopped / waiting / needs_attention / running. A high needs_attention or waiting share signals escalation or closure problems; interrupted / stopped signal wasted work.
• Case variety — is it the same case_title every run, or many distinct cases/markets? Repetition of one title across Runs means a case that won't close; wide variety means real throughput.
• Eval scores — for each Run's eval_summaries: is passed to run-debugger for the transcript-level cause".

If the user asked only about one dimension ("is this Agent over-escalating?"), answer that dimension with its counts and skip the rest.

Reading the request

1. Find the Agent or Queue reference in the conversation. If absent, ask before reading.
2. Determine scope. Single Agent ("audit this Agent") vs. workflow ("why does this queue back up", "analyse this producer→consumer flow"). The first profiles one Agent's Runs; the second adds the topology and reads both AOPs.
3. Determine the lens. Efficiency (speed, cost, wasted Runs, batching) vs. quality (eval scores, recurring defects) vs. reliability (closure, escalation). Lead with the lens the user named; surface the others only if the data makes them unavoidable.

You have no access to anything outside your tool list (API mode) or what the user shared (paste mode). Do not infer the contents of Files, Connections' upstream systems, or Runs you didn't pull. The run set, the topology, and the AOPs are the source of truth.

Final check before returning

Walk through this once on your draft. Fix anything that fails.

• [ ] Every finding is grounded in evidence fit to it — counts across the run sample for behavioural patterns, the topology / problems / Queue backlog for structural ones — not a single Run and not a hunch.
• [ ] You read the AOP the Runs actually ran (build_id), not just the current Build.
• [ ] For a queue workflow, you read both producer and consumer AOPs and checked listQueueAgents problems.
• [ ] Each inefficiency is named from the taxonomy and carries its evidence.
• [ ] Each prompt change quotes the exact AOP line to change and names the artifact.
• [ ] AOP rewrites are handed to aop-writer, not written here.
• [ ] Duvo terminology used: Agent, Run, Build, AOP, Connection, Queue, Files, Setup.
• [ ] You did not invent run counts, eval comments, AOP lines, or topology the data doesn't show.

Duvo terminology

Use Duvo's nouns when describing the workflow and the fix. Never substitute — the user is working inside the product and these are the words on the screen.

| Use | Not | | ---------- | ----------------------------------- | | Agent | assignment, AI teammate, bot | | Run | task, job, execution | | Build | revision, version | | AOP | SOP, instructions, prompt, playbook | | Connection | integration, account | | Queue | case queue, backlog | | Files | knowledge base, documents | | Setup | configuration, config |

See also

• run-debugger — for one failed Run: it reads the transcript and the Build that ran it. This skill audits the whole workflow; hand it a representative Run when a pattern needs transcript-level depth.
• aop-writer — once you've named an AOP-level fix, hand off the in-effect AOP and the change request; this skill never rewrites AOPs itself.
• duvo-cli — the terminal surface for every read here (duvo runs list, duvo queues agents, duvo revisions get); useful when the user is auditing from a shell.

Resources

• Duvo — product website
• Duvo documentation — building Agents, AOPs, Connections, Queues
• Web app — open the Agent, inspect its Runs, evals, and the Build that ran them
• Duvo CLI (@duvoai/cli) — the read commands this

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: duvoai
• Source: duvoai/skills
• License: MIT
• Homepage: https://www.duvo.ai

Install and usage instructions live in the source repository linked above.