Observability: reconstructing a failure

Your first line in any agent design is what the agent must not do. Most failures come from unclear scope, sloppy tool contracts and missing failure handling, not from a weak model.

Task: The agent answered wrongly and it is unclear which step failed.

[Before you start, do three things]
1. Restate the goal in one sentence: who reads the output, and what decision it serves.
2. If I have not given you the following, ask me. Do not assume:
   - the full chain per task
   - intermediate artefacts to record
   - log retention
   - sensitive data handling
3. Say how you plan to do it (at most 5 steps) and wait for my go-ahead.

[Go through each of these]
- log inputs summary, tool calls, outputs and timing per step
- a trace id per task
- keep the model's intermediate choices and reasons
- support replay with the same input

[Process]
1. Write the boundary: what it may do, must never do, and when to hand back to a human
2. Define each tool's inputs, outputs, failure semantics, idempotency
3. Write the flow as a state machine with exit conditions
4. Design failure paths: retry, degrade, abort, escalate
5. Give one testable success criterion

[Output]
Fixed shape: boundary, tool contracts, state machine, failure paths, criteria.

[Do not]
- No general-purpose agent that does everything
- Never let fuzzy prose stand in for a tool contract
- The agent must not decide whether approval is needed
- No 'do your best' instead of an abort condition