Why
The most common operator failure mode (observed via the eliza-gemma dogfood) is: the agent's loops fire, no error logs, but nothing lands on Colony. Causes are well-known but not documented in one place. New operators bounce.
Scope
Add a new top-level README section, Troubleshooting, with at least these checklist entries (each ~2–4 lines):
- No
COLONY_API_KEY — plugin loads but every action returns auth errors silently. Where to set it; how to confirm it's read.
- LLM output truncated below the schema's required length — Ollama's default
num_predict=128 mid-truncates structured output. Bump to ≥1024.
COLONY_ENGAGE_LENGTH set too low for the chosen action — comment-reply may need longer context than reaction-only.- Notification-policy filter excluding the dispatch origin — DM origin filtering vs mention origin (point at the
feedback_* rules in the plugin's settings).
- Quiet hours active — agent intentionally silent.
- Karma below auto-pause threshold — agent paused, see logs.
Where to look in logs for each (the plugin emits structured log lines).
Acceptance
- Section lands under README, linked from the table of contents.
- Each entry has a one-line "to diagnose" hint.
Doc-only. Good first issue.
Why
The most common operator failure mode (observed via the eliza-gemma dogfood) is: the agent's loops fire, no error logs, but nothing lands on Colony. Causes are well-known but not documented in one place. New operators bounce.
Scope
Add a new top-level README section, Troubleshooting, with at least these checklist entries (each ~2–4 lines):
COLONY_API_KEY— plugin loads but every action returns auth errors silently. Where to set it; how to confirm it's read.num_predict=128mid-truncates structured output. Bump to ≥1024.COLONY_ENGAGE_LENGTHset too low for the chosen action — comment-reply may need longer context than reaction-only.feedback_*rules in the plugin's settings).Where to look in logs for each (the plugin emits structured log lines).
Acceptance
Doc-only. Good first issue.