Find out why something failed
Inspect workflow, worksheet, and sequence evidence to diagnose a failed run.
Use this guide when a worksheet cell, Sequence, Workflow, or provider-backed run has an outcome you cannot explain. It is a diagnosis play, not a retry button. The diagnostics skill starts from the object an operator can see, follows it to the owning run, and separates queued, paced, unknown, and genuinely failed states. It connects runs to the relevant worksheet cell, Sequence, or Workflow.
Architect uses diagnostics and the owning pack's reads. It asks one question with the least evidence that settles it, rather than dumping every log or switching providers. The useful result is a plain-language answer backed by an object link, run state, structured error when present, a bounded repair, and a readback of the repair.
Needs and produces
Start with the specific object: a cell, a column, a source run, a sequence enrollment, a sender, or a workflow graph. Keep its link and identify the question: where did this value come from, which rows failed, why has a sequence not sent, or why did work cost more than expected. Reads establish the evidence before a mutation. Pending, queued, paced, capped, and unknown are not failures and none means zero.
The outcome is a diagnosis that distinguishes state from defect. It names the current run, attempt, provider, charged credits, and structured error when the result supplies them. It also says whether the repair can repeat an external action or spend credits. A good diagnosis never claims a retry is safe merely because the original request returned without an obvious error.
Follow the object to its evidence
Open the object the user sees, then read the owning run. Classify it as running, queued, paced by a cap or sending hours, waiting on an upstream column, blocked by a missing connection, an empty provider answer, failed with an error, or a likely product defect. Quote the state or error that establishes this classification. A run still computing a count cannot establish that count as zero.
For a worksheet value, read the cell, its column, and the run that settled it. A column empty on every row often was added after rows landed and never ran on them, or its gate reads a column that has not settled. A score stuck in place often waits on an evidence column that failed or remains running. Empty and failed cells are different answers. Missing provider data is unknown, not false evidence.
For an outbound issue, read Sequence state, enrollment, sender connection, sending hours, and caps. An enrolled but silent Sequence might not be started. For a cost question, read finished runs and charged credits. A sample run repeated from the top can bill the sample twice, and contact data before a fit gate can spend on rows that never qualified.
Repair only the failed scope
The repair follows the classification. Continue remaining rows instead of rerunning a completed sample. Retry only failed rows or a failed workflow node. Move a gate when it reads an unsettled input. Connect the named account when the run explicitly needs it. A source attachment can return a repair whose kind is fix_input with a hint. Correct that input and retry the corrected payload before reporting a block.
Do not hide a defect with a manual cell edit or another provider. A manual value bypasses provenance when a column run should settle the value. A daily cell limit is workspace pacing, not a worksheet defect. Cancel a run only when the user wants it stopped, then read its final state. A succeeded step with a receipt should not run again.
- 1
Name one question
Usediagnosticsto state the object and the exact unknown. The operator checks the visible object link before the investigation broadens. - 2
Read the owning run
Inspect state, attempt, provider, charge, events, and structured error. Distinguish queued, running, paced, empty, failed, and unknown before choosing a repair. - 3
Find the upstream cause
For cells, read column inputs and gates. For Sequences, read enrollment and sender state. For Workflows, read graph validation and the failed node. - 4
Apply the narrow repair
Retry failed rows or one node, correct a returned input hint, attach a missing connection, or wait and read a still-running result. State any new credit scope first. - 5
Read back and report
Read the repaired object and its final run. Report only what that result proves, including identifiers needed to report a likely defect.
Credits and leading metric
Diagnosis starts with reads. A repair that reruns a provider-backed source or column can spend credits, so limit it to the failed selection and inspect its estimate. The finished run supplies the charge. Do not infer cost from a queued result or repeat a whole column when only the remaining rows need work.
The leading metric is an answer supported by an object link, state, and a bounded next action. For a worksheet, report duplicate and empty counts separately from failed cells. For a sequence, report draft, validated, published, enrolled, started, or delivered as distinct facts. For a workflow, report the validated graph and current run state rather than treating creation as execution.
When it goes wrong
If a status read times out, it changed nothing and says nothing about the run. Read again and follow a queued or running run to a terminal result. If a provider answer is empty, preserve that finding rather than substituting a similar row. If an upstream column is unresolved, fix or wait for it before asking a dependent score or gate to decide anything.
When the state points to a product defect, keep the object and run identifiers, the exact quoted error, and the failed scope. Do not run an unbounded workaround. When a sequence has an unknown send result, read the conversation and delivery state before any retry. When no repair is supported by the evidence, report the limitation, what was checked, and the one next read or connection that unblocks the work.
Do not keep reading after the question has an answer. Do not replace a bounded repair with a broad rerun. A run that is still queued may be working normally. A paced run identifies a workspace or sender limit. A missing account identifies a connection dependency. A failed cell identifies a distinct error state. An empty provider answer records an unknown fact. A receipt proves a completed external step. A saved object does not prove its downstream run completed. A user-visible link makes the evidence reviewable. These distinctions keep a diagnostic report actionable. They also prevent repeat charges and duplicate delivery. Preserve the exact state when escalation is necessary. Read the final state after cancellation or repair.