When Something Breaks
The five-minute diagnostic loop that fixes most broken bots before you touch any settings.
Your bot was great on Tuesday and today it’s silent, repetitive, or confidently wrong. Before you nuke it and start over, run the loop below. It resolves most issues in one or two passes.
The five-minute loop
1. Name the symptom precisely. Not “it’s broken,” but one of: no output at all, wrong output, output stopped mid-run, ran but didn’t use the tool, repeats things it already did. The symptom picks the suspect list.
| Symptom | Usual suspects |
|---|---|
| Silent | routine paused, quota exhausted, report destination changed |
| Wrong output | role drift, missing config file, ambiguous instructions |
| Repetition | state file missing, not read, or never updated |
| Tool ignored | access revoked, tool renamed, prompt no longer mentions it |
| Half-finished | output limit hit mid-format; report too long |
2. Ask the bot to show its work. In the same chat: “Show me the files you read this run and summarize your last routine run.” You are asking for its view of the world. A missing or stale file explains most mysteries instantly.
3. Re-read the prompt as if you were the bot. Ambiguity compounds at scale. “Check my channels” — which ones, where is the list, what counts as new? If the answer isn’t in the prompt or a file, the bot is improvising, and improvisation drifts.
4. Change one thing, then re-run. Restore the file, re-pin the schedule, or tighten one instruction — never all at once. Then force a re-run instead of waiting for tomorrow: “Run your routine now, using the same steps.”
5. Write down the fix. Add a line to a fixes.md in its workspace: symptom → cause → change. Bots forget incidents; files don’t. The third time you fix the same thing, that note converts into a new instruction.
The three chronic diseases
Prompt rot. You edited the role five times and now two instructions contradict. Fix: keep the role under ~20 lines; move history and edge cases into files the bot reads, not the prompt itself.
File rot. channels.md has a dead entry; seen.md grew into a novel. Fix: schedule a monthly prune — “list entries you haven’t used in 30 days and propose removing them.”
Access rot. A token expired, a plugin was renamed, an inbox password rotated. The bot will usually not announce this — it just degrades quietly. Fix: when output quality drops for no visible reason, check access first, prompt second.
When to rebuild instead
If the prompt has more patch lines than original lines, start clean: copy the files, rewrite the role from your fixes.md, and redeploy. Ten minutes of fresh thinking beats an hour of archaeology.
The troubleshoot hub has a full symptom-by-symptom playbook if you want to go deeper.