Find the run. actions_list with method: list_workflow_runs and the workflow's id or file name as resource_id. Narrow with workflow_runs_filter — branch and event for the change you care about. Note that its status filter covers the lifecycle only (queued, in_progress, completed); there is no filter for the outcome, so filter to completed and read conclusion off the results.
Confirm you have the right run. actions_get with method: get_workflow_run. Check conclusion, head_branch and head_sha before spending anything else. A failure on a stale commit may already be fixed.
Narrow to the failing jobs. actions_list with method: list_workflow_jobs and the run id as resource_id. Most runs fail in one job; the rest are noise.
Read the logs of just those jobs. get_job_logs with run_id and failed_only: true returns every failed job's log in one call. Set return_content: true — without it you get links, not text — and raise tail_lines from its default of 500 only if the failure is not in the tail.
Locate the failing step. actions_get with method: get_workflow_job returns the job's steps with a per-step conclusion. The first non-successful step is where to look; the log lines around it are the evidence.
Classify the failure using the decision points below. If the first read is ambiguous, follow references/failure-classes.md.
Decide: hand the diagnosis back, or propose a rerun and ask first.
Report the workflow, the job, the step, the cause, and what you propose — not just that it failed.

Decision points

Classify before acting. The class decides whether a rerun is even meaningful:

Code failure — a test, build or check failed on its own merits. Reruns change nothing. Report the step and the evidence and stop.
Infrastructure failure — a lost runner, a timeout, a connection reset midway. A single rerun is reasonable.
Configuration failure — a missing secret, an unavailable permission, a bad ref. Reruns change nothing until the configuration changes. Say what is missing.
Cancelled — find out whether a person cancelled it or a concurrency rule superseded it before treating it as a failure at all.
Still going — status is in_progress and there is no conclusion yet. Wait; do not diagnose a run that has not finished.

If a rerun is justified, choose between the two forms deliberately:

rerun_failed_jobs — reruns only what failed and keeps the successful jobs and their logs. Cheaper, faster, and it preserves the evidence. Prefer it.
rerun_workflow_run — reruns everything. Only when earlier jobs produced state that must be rebuilt, or when you suspect the successful jobs are wrong too.

One rule holds across every class: never rerun the same run twice without something having changed. A second identical rerun is not diagnosis, and a run that goes green on the third attempt is a finding, not a fix.

Fields that matter

status and conclusion — the pair most often confused. status is where the run is in its lifecycle; conclusion (success, failure, cancelled, timed_out, skipped) only exists once it has finished. Reading status: completed as "it worked" is the single most common mistake here.
head_sha and head_branch — which code actually failed. Compare against what the request is about.
The attempt number on the run — a rerun adds an attempt rather than replacing the earlier one, so an apparently new failure may be the third look at an old problem. Check it before proposing yet another rerun.
run_id versus job_id — get_job_logs needs run_id when using failed_only, and job_id when pulling one job. Every actions_run_trigger method except run_workflow keys off run_id.
event — pull_request, push, schedule and workflow_dispatch runs have different permissions and different audiences. A scheduled failure at 03:00 is not the same problem as one blocking a pull request.
steps[].conclusion — the difference between "the job failed" and "step 6 of 11 failed".

Confirm before rerunning or cancelling

actions_run_trigger writes. Every method it offers changes what is running or what evidence survives, so none of them are part of looking around.

Rerunning costs runner time and can re-trigger deployments or notifications. Name the workflow and the run, say which form you intend, and say why the outcome is expected to differ this time. If the honest answer is "it might be flaky", say that — and get agreement rather than assuming it.
cancel_workflow_run stops work someone may be waiting on. Name the run, the branch and the actor who started it, and ask before stopping it.
run_workflow starts something new rather than repeating something old. Confirm both the ref and any inputs, since those decide what it does.
delete_workflow_run_logs destroys the evidence you are triaging, permanently. It has no place in this workflow. Do not offer it as a step.

Empty and failure cases

These look alike from a distance and must be reported apart:

No runs returned — the workflow may never have been triggered on that branch, the filters may be too narrow, or Actions may be disabled for the repository. Say which you could not distinguish rather than reporting "no failures".
The run has not finished — report status and stop. A run without a conclusion has not failed.
Logs unavailable or empty — retention expires, and logs for a very old run may be gone. Fall back to the job's steps for which step failed, and say the log itself was unavailable.
The log looks truncated — tail_lines cut it. Raise it, or pull the single job by job_id, before concluding anything about the cause.
A job failed with nothing in its log — it likely never started because a job it depended on failed first. Report the upstream job instead.
A rerun or cancel is refused — permissions, or a run too old to rerun. Report plainly which call failed and on which run; do not retry it silently or substitute a different method.

Never infer that something passed from the absence of a failure. Say what you saw, and say what you could not see.

workflow-failure-triage

Triaging a failing workflow run

Sequence