Debug

Keep working notes in the active task. Do not add repository debug-log files. At the start of a fresh investigation, use consult-echo when repository policy requires prior-work search. During continued diagnosis or mitigation of the same incident, reuse results already read instead of invoking consult-echo again unless the scope or freshness requirement changes or the user asks for a new search. After diagnosing a live infrastructure incident, use write-ops-log to publish its standalone Echo record and link it from the associated PR or issue. A code bug or local debugging session is not an incident unless it caused a service, production run, or shared operational system to fail or degrade.

Infrastructure faults

Read lib/iris/AGENTS.md or lib/zephyr/AGENTS.md for context, then follow the matching OPS.md section:

Symptom	Read
Stuck job, scheduling failure, resource leak, controller stalled	lib/iris/OPS.md → SQL Queries, Process Inspection & Profiling, Known Bugs, Troubleshooting
Iris task misbehaving, container inspection, profiling a running task	lib/iris/OPS.md → Task Operations, Process Inspection & Profiling
Zephyr pipeline slow / stragglers / data skew / worker failures	lib/zephyr/OPS.md → Diagnostic Patterns, Observability
TPU bad node (No accelerator found, FAILED_PRECONDITION, Device or resource busy)	lib/iris/OPS.md → TPU Bad-Node Recovery

Read the guardrails beside the commands. Never modify the controller database, prefer iris process profile over SSH, and never run a full iris cluster restart without approval. After a TPU recovery or Zephyr fix, return to the active Iris job-monitoring or babysit-zephyr loop.

Code bugs

For code bugs, reproduce the failure, identify the smallest falsifiable hypothesis, change one cause at a time, and test the behavior that failed. Let exceptions propagate unless added context changes the diagnosis.