diagnose-skill-run

Diagnose Skill Run

Diagnose what went wrong in a skill or graph execution and propose the smallest change that fixes it.

Resolve receipt_id through the native ledger read runner, then combine its redacted receipt detail with the supplied failure summary or harness output. The native detail is authoritative for status, verification, authority, acts, decisions, criterion status, references, and seal posture. It deliberately excludes hydrated step output, stdout, stderr, credential values, context bodies, and local paths; those details must come from supplied bounded failure evidence when they are necessary.

Distinguish root cause from symptoms. A graph may report failure at step 4, but the root cause may be bad output from step 2 that propagated through context passing. Trace data flow backward through context edges to find where the problem originated.

Classify the failure:

• Input error — required input missing or malformed. Fix: input validation or input resolution.
• Scope denial — step requested scopes outside the graph grant. Fix: scope declarations or grant configuration.
• Tool failure — CLI tool or adapter returned an error. Fix: tool invocation (args, env, cwd) or the tool itself.
• Schema mismatch — step output did not match expected shape for downstream context. Fix: output parsing or artifact contract.
• Timeout — step exceeded time budget. Fix: increase timeout, reduce work, or split the step.
• Policy denial — transition gate blocked the step. Fix: gate conditions or upstream output.
• Review rejection — adversarial review found blocking issues. Fix: the code or spec, not the review process.
• Harness assertion — fixture expectations did not match actual output. Fix: skill logic or stale fixture expectations.

Composes

• ledger#read

Agent-mediated suspension is not a failure

A receipt sealed with reason needs_agent, or whose graph status is deferred, denotes a healthy agent-mediated suspension, not a defect. The runtime yielded to the caller for missing agent or human input. This is a normal part of graph execution, not one of the failure classes above. When the only evidence is needs_agent without any exit code, scope denial, schema mismatch, or other concrete failure signal, return verdict: pass with an empty improvement_proposals array and note that the graph is paused as designed.