clawdoc

# clawdoc

Examine agent sessions. Diagnose failures. Prescribe fixes.

## Invocation modes

### `/clawdoc` (slash command — default: headline mode)
Produces a compact, tweetable health check:
```
🩻 clawdoc — 3 findings across 12 sessions (last 7 days)
💸 $47.20 spent — $31.60 was waste (67% recoverable)
🔴 Retry loop on exec burned $18.40 in one session
🟡 Opus running 34 heartbeats ($8.20 → $0.12 on Haiku)
🟡 SOUL.md is 9,200 tokens — 14% of your context window
```
Run: `bash {baseDir}/scripts/headline.sh ~/.openclaw/agents/main/sessions`

### `/clawdoc full` or "give me a full diagnosis"
Runs all 14 pattern detectors and produces the complete diagnosis report with evidence and prescriptions.

### `/clawdoc brief` or "clawdoc one-liner for daily brief"
Single-line summary for morning cron integration:
```
Yesterday: 8 sessions, $3.40, 1 warning (cron context growth on daily-report)
```
Run: `bash {baseDir}/scripts/headline.sh --brief ~/.openclaw/agents/main/sessions`

### Natural language triggers
Also activates when user says: "what went wrong", "why did that fail", "debug", "diagnose", "why was that so expensive", "where are my tokens going", "cost breakdown", "health check", "check my agent", "what's wrong", "examine"

## Quick examination — most recent session

Find the most recent session file and run:
```
bash {baseDir}/scripts/examine.sh <session.jsonl>
```
This outputs a JSON summary with turns, cost, token counts, tool call frequency, and error count.

## Single-session diagnosis

Run all 14 pattern detectors against a specific session file:
```
bash {baseDir}/scripts/diagnose.sh <session.jsonl> | jq .
```

## Diagnosis with prescriptions

Pipe diagnose output into prescribe for a formatted report with fix recommendations:
```
bash {baseDir}/scripts/diagnose.sh <session.jsonl> | bash {baseDir}/scripts/prescribe.sh
```

## Cost breakdown

Show per-turn cost waterfall for a session:
```
bash {baseDir}/scripts/cost-waterfall.sh <session.jsonl> | jq '.[0:5]'
```

## Cross-session pattern recurrence

Analyze pattern recurrence across multiple sessions in a directory:
```
bash {baseDir}/scripts/history.sh <sessions-dir> | jq .
```

## Full diagnosis

When the user wants a comprehensive diagnosis, run the scripts above and synthesize findings into this report format:

### Diagnosis report format

```
## 🩻 Diagnosis — [date]

### Patient summary
- Sessions examined: N
- Period: [date range]
- Total spend: $X.XX
- Total tokens: XXk in / XXk out

### Findings

#### 🔴 Critical
[Infinite retry loops, context exhaustion, tool-as-text failures]
Each finding includes: what happened, evidence, estimated cost impact, and specific prescription.

#### 🟡 Warning
[Cost spikes, model routing waste, cron accumulation, compaction damage, workspace overhead]

#### 🟢 Healthy
[What's working well — efficient sessions, good model routing]

### Prescriptions (ranked by cost impact)
1. [Highest-impact fix with specific config change or command]
2. [Second highest]
3. [Third]

### Cost breakdown
[Per-day costs for the examination period]
[Top 3 most expensive sessions with root cause]
```

## Pattern reference

| # | Pattern | Severity | Key indicator |
|---|---------|----------|--------------|
| 1 | Infinite retry loop | 🔴 Critical | Same tool called 5+ times consecutively |
| 2 | Non-retryable error retried | 🔴 High | Validation error → identical retry |
| 3 | Tool calls as text | 🔴 High | Tool names in assistant text, no toolCall blocks |
| 4 | Context window exhaustion | 🟡-🔴 | inputTokens > 70% of contextTokens |
| 5 | Sub-agent replay | 🟡 Medium | Duplicate completion messages in parent |
| 6 | Cost spike | 🟡-🔴 | Session cost > 2x rolling average |
| 7 | Skill selection miss | 🟢 Low | "command not found" after skill activation |
| 8 | Model routing waste | 🟡 Medium | Premium model on heartbeat/cron |
| 9 | Cron context accumulation | 🟡 Medium | Growing inputTokens across cron runs |
| 10 | Compaction damage | 🟡 Medium | Post-compaction tool call repetition |
| 11 | Workspace token overhead | 🟡 Medium | Baseline > 15% of context window |
| 12 | Task drift | 🟡 Medium | Post-compaction directory divergence or 10+ reads without edits |
| 13 | Unbounded walk | 🟠 High | Repeated unscoped find/grep -r flooding output |
| 14 | Tool misuse | 🟡 Medium | Same file read 3+ times without edit, or identical search repeated |

## Self-improving-agent integration

To enable writing findings to `.learnings/LEARNINGS.md`, set `CLAWDOC_LEARNINGS=1` before running prescribe:
```
CLAWDOC_LEARNINGS=1 bash {baseDir}/scripts/diagnose.sh <session.jsonl> | bash {baseDir}/scripts/prescribe.sh
```

## Tips

- Session JSONL files are the ground truth for all diagnostics
- Use `jq -s` (slurp) for aggregations across all lines in a session file
- Filter `message.content[]` by `type=="text"` for readable content, `type=="toolCall"` for tool invocations
- When prescribing config changes, always show the exact JSON path and value