Clawdoc

Diagnose OpenClaw agent failures, cost spikes, and performance issues with 14 pattern detectors. Use when: task failed unexpectedly, costs seem high, agent b...

Security Scan

Clawdoc is internally coherent: its scripts, required binaries, and runtime instructions match the described purpose of diagnosing agent session logs and do not request unrelated credentials or network access.

Purpose & Capability

Name/description match the requested binaries (bash, jq, bc) and the provided scripts implement 14 detectors for JSONL agent sessions. Nothing requested (no cloud credentials, no unusual binaries) appears unrelated to a local diagnostics tool.

Instruction Scope

SKILL.md instructs running local scripts against explicit session JSONL files or a user-provided sessions directory. The tool only reads session files, produces JSON findings, and — only if opt-in via CLAWDOC_LEARNINGS=1 — writes a local .learnings/LEARNINGS.md file. There are no instructions to contact external endpoints, harvest unrelated config, or automatically search system paths without explicit user input. Note: helper/dev scripts (e.g., convert-claude-sessions.sh) will scan an input directory you provide and may run find/grep on paths you pass — review the path you give to avoid scanning sensitive large trees.

Install Mechanism

No install spec is provided (instruction-only install), and there are no downloads or remote installers referenced. Code is shipped as shell scripts in the package; risk is limited to running those scripts locally. No extract-from-URL or third-party package installs are present.

Credentials

The skill requires no environment variables or credentials to run. The only optional environment flag (CLAWDOC_LEARNINGS=1) enables a local write to .learnings/LEARNINGS.md and is opt-in. No secrets or unrelated environment/config paths are requested.

Persistence & Privilege

always is false and the skill is user-invocable. It does not request persistent platform privileges or modify other skills. The only persistence is an opt-in local write when CLAWDOC_LEARNINGS is set; scripts otherwise operate on files you explicitly pass.

Assessment

This appears to be a legitimate local diagnostics skill. Before running it: (1) Inspect the scripts (they are plain shell + jq) and confirm you trust them in your environment. (2) Run the demo (generate-demo.sh) to see behavior on synthetic data. (3) When diagnosing real sessions, supply explicit paths (avoid passing / or other broad roots to convert or headline scripts). (4) Only set CLAWDOC_LEARNINGS=1 if you want findings written into a local .learnings/LEARNINGS.md file. (5) Ensure dependencies (jq, bash, bc) are installed and run the test suite (make test) if you want extra assurance.

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