| name | debug |
| description | Debug code bugs or Iris/Zephyr/TPU infrastructure faults with a structured incident record. |
Skill: Debug
Systematic debugging for code-level bugs and Marin infrastructure faults.
For infrastructure symptoms, route to the right OPS.md section first. Publish
durable investigation records to Echo with write-ops-log.
Do not add repository debug-log files. Use write-ops-log to finish an
infrastructure or other multi-step incident as a standalone Echo postmortem.
Consult Echo
Invoke consult-echo at the start when prior discussions, decisions, or
incident patterns could materially shorten debugging. At resolution, always
invoke it to search before deciding whether the reusable lesson belongs in
OPS.md, docs/, the Echo incident record, or an existing or new synthesis.
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 |
Operational guardrails (never modify the controller DB, prefer
iris process profile over SSH, never run a full iris cluster restart
without approval) live next to the relevant commands in OPS.md — read those
sections. After a TPU recovery or zephyr fix, return to the active babysit
loop (babysit-job or babysit-zephyr).
Code bugs
For code-level bugs that are not infrastructure faults, keep working notes in
the active task. A contained fix may use the lightweight structure below.
Publish the complete write-ops-log structure to Echo when the investigation
exposes a durable operational lesson:
# <System or component>: <symptom>
<goal>
## Initial status
<initial status, as reported or observed>
## <Hypothesis N>
The suspected source of the bug, or a change needed to isolate it.
## Changes to make
Which files you are altering and how.
## Results
Test results and any new hypotheses. Repeat the Hypothesis/Results cycle as needed.
## Future work
- [ ] Cleanups observed along the way
