research-troubleshoot

name	research-troubleshoot
description	Diagnose why a task or agent failed. Check local data first (zero tokens), web search only if needed.
tags	["research","troubleshoot","diagnosis","zero-cost"]
version	1.0.0

research-troubleshoot

Diagnose task or agent failures. LOCAL FIRST — models are the LAST resort.

When to use

• Task failed and nobody knows why
• Agent has high failure rate
• Pattern of similar failures across multiple tasks
• Babysitter flags an agent for repeated violations

Process (ordered by cost — cheapest first)

Step 1: Local data (zero tokens)

ops_query: SELECT id, agent, status, substr(task,1,80), substr(errors,1,200), substr(outcome,1,200), duration_ms FROM tasks WHERE agent='<agent>' AND status IN ('blocked','failed','cancelled') ORDER BY id DESC LIMIT 10

Look for:

• Repeated error patterns (same error across tasks = systemic)
• Timing patterns (all fail at same time = infrastructure)
• Engine patterns (all gemini-run fail = engine broken, not task broken)

Step 2: Chart search (zero tokens)

chart search "<error keyword>"
chart search "<agent name> failure"
chart search "issue-<pattern>"

Someone may have already diagnosed and charted this.

Step 3: Log scan (zero tokens)

ops_query: SELECT key, substr(value,1,200) FROM kv WHERE key LIKE 'truth_violation_%' AND value LIKE '%<agent>%' ORDER BY key DESC LIMIT 5

Check executor log, stability log, babysitter log for the timeframe.

Step 4: Engine health check (zero tokens)

ops_query: SELECT engine, COUNT(*), SUM(success), ROUND(AVG(duration_ms)) FROM engine_usage WHERE engine='<engine>' GROUP BY engine

If engine success rate is low, the problem is the engine, not the task.

Step 5: Web search (free — only if Steps 1-4 insufficient)

Use web-search skill with specific error message or pattern. Example: "OpenClaw codex-run exit code 124 timeout" or "NVIDIA NIM API headers timeout error"

Step 6: Model synthesis (costs tokens — only for complex diagnosis)

Only after Steps 1-5 have gathered data. Summarize findings, propose fix.

Output Format

## Diagnosis: [Agent/Task #ID]
**Pattern**: [What's failing and how often]
**Root cause**: [Infrastructure/Engine/Prompt/Logic]
**Evidence**: [Which step found it, what data]
**Fix**: [Specific action — file, line, change]
**Prevention**: [Chart to add, policy to enforce]
**Cost of diagnosis**: [Zero / Free web search / N tokens]

Chart findings immediately

Every diagnosis = a chart. Even "I couldn't find the cause" is worth charting to save the next investigator time.