Skip to main content

Debug failed agent task

Use this page when an agent-owned task is stuck, rejected, or missing the evidence needed to explain why it did not close out correctly.

When to use this page​

  • A task is not progressing through its expected lifecycle.
  • A task was rejected or timed out and the owner boundary is not obvious yet.
  • Closeout evidence is missing even though execution appeared to start.

Prerequisites​

  • You can capture the task identifier and current visible state.
  • You can collect state and evidence before retrying or requeueing anything.

Architecture / Flow​

Step-by-step procedure​

1. Classify where the task stopped​

Decide whether the task is stuck:

  • before execution
  • during execution
  • at closeout or evidence publication

2. Capture the minimum useful evidence set​

Record:

  • task identifier
  • current task state
  • last visible transition
  • any rejection, timeout, or missing-evidence signal

3. Narrow the owner boundary before mutation​

Use the evidence to decide whether the problem points first to:

  • Pattern orchestration
  • Warp execution
  • Reed-side evidence or closeout handling

4. Prefer readback over blind retry​

Use canonical owner troubleshooting and task readback commands first. Do not requeue or retry while the owner split is still ambiguous.

5. Verify the recovery at the state boundary that failed​

After the bounded fix, confirm:

  • the task progresses to the next expected state
  • or the missing closeout evidence now exists

Verification​

This runbook is being used correctly when:

  1. the task phase is classified before retry or requeue
  2. the owner boundary is narrowed from evidence
  3. the fix is validated by a new state transition or restored closeout evidence

Common failure modes​

Retrying before capturing state evidence​

Problem:

  • the best clue about the failure phase is lost.

Better path:

  • capture task identifier, last state, and rejection signal first

Treating Pattern and Warp ownership as interchangeable​

Problem:

  • troubleshooting jumps between repos without a clear boundary.

Better path:

  • classify whether the task failed before execution, during execution, or during closeout

Source Truth​

  • contracts/docs/public_manufacturer_docs_post_v1_runbooks_v1.json
  • JaddaHelpifyr/jhf-warp:docs/TROUBLESHOOTING.md
  • JaddaHelpifyr/jhf-pattern:docs/TROUBLESHOOTING.md
  • JaddaHelpifyr/jhf-reed:docs/TROUBLESHOOTING.md

Next paths​