skills.rest
skurekjakub
skurekjakubCOMMUNITY
Explore all skills by this author →
GitHub

cli-debug-log-analysis

Extract subagent invocation spans and tool usage from Ralph CLI debug logs.

Updated Apr 1, 2026
Search Tags:#debugging#subagent#log-analysis#tool-calls#token-usage#context-compaction#cli-debug-log
One-click install
npx skills add https://github.com/skurekjakub/docwriter-agent --skill cli-debug-log-analysis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cli-debug-log-analysis
Source: https://github.com/skurekjakub/docwriter-agent/tree/main/.github/skills/cli-debug-log-analysis
Command: npx skills add https://github.com/skurekjakub/docwriter-agent --skill cli-debug-log-analysis

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Parse and analyze Ralph CLI debug logs (cli-debug.log) to extract subagent spans, tool call sequences, token consumption, context compaction events, and error patterns. Use this skill when you need to manually parse a cli-debug.log file — for example when the subagent-mapper's pre-extracted data is insufficient or missing, when debugging a specific subagent's behavior in detail, or when investigating infrastructure issues visible only in raw logs. Trigger on phrases like 'parse the debug log', 'extract subagent spans', 'analyze tool calls from the log', 'what happened in the cli-debug log', or 'dig into the raw log'.

Core Features & Use Cases

  • Subagent span extraction: identify the start and end of each subagent invocation and pair them with the resolved model.
  • Tool call sequencing: map function/tool calls within each subagent span to reconstruct the execution trace.
  • Telemetry consolidation: capture token usage and context window metrics (e.g., context compaction events) for performance analysis.
  • Debugging aids: provide targeted extraction recipes to investigate infrastructure issues, model fallbacks, or tool failures.

Quick Start

Analyze a cli-debug.log to map subagent spans, tool calls, and token usage for a given run.

Frequently Asked Questions about cli-debug-log-analysis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I extract subagent spans from a CLI debug log?▼

Map tool calls within a CLI debug log by locating tool_call_executed events and grouping them within their respective subagent span boundaries to reconstruct the execution trace accurately.

What is the best way to analyze token usage and context compaction in CLI logs?▼

Analyze token usage and context compaction in CLI logs by capturing assistant_usage metrics and CompactionProcessor events to evaluate context window limits and overall performance during subagent execution.

How do I debug Ralph CLI infrastructure issues visible only in raw logs?▼

Debug Ralph CLI infrastructure issues in raw logs by applying targeted grep, sed, and awk extraction recipes to isolate errors, model fallbacks like "falling back to session model", and tool failures from cli-debug.log.

When should I manually parse a cli-debug.log file instead of using pre-extracted mapper data?▼

Manually parse a cli-debug.log file when pre-extracted mapper data is incomplete or missing, when debugging a specific subagent's behavior in detail, or when investigating infrastructure issues visible only in raw logs.

Can I use grep and awk to investigate model fallbacks in CLI debug logs?▼

Yes, you can use grep and awk to investigate model fallbacks in CLI debug logs by searching for getOrCreateAgent.*final model events and "falling back to session model" messages to diagnose resolution failures.

Related Skills

Explore More Software Engineering Skills→
mDevsLabsmDevsLabs
1

heterogeneous-agent

Diagnose heterogeneous-agent pipeline failures across CLI adapters, IPC, and tool chains.

Community
Advanced
DojoGenesisDojoGenesis
2

tool-intercept-logger

Log tool executions with OTEL-compatible spans in SQLite.

Community
Advanced
majidraza1228majidraza1228

build-review-interface

Render LLM trace data in a browser for Pass/Fail labeling and JSONL export.

Community
Intermediate
rileyhilliardrileyhilliard
127

reading-logs

Analyze application logs with grep, awk, sed, and jq to identify errors and patterns.

Community
Intermediate