self-improvement

Self-Improvement Loop Analysis

Analyze autonomous Claude Code session metrics, track improvement efforts, and monitor efficiency trends.

Prerequisites

This skill is designed for projects using an autonomous Claude Code loop with structured task tracking:

• ralph-wiggum loop — A bash script (ralph-wiggums-loop.sh) that runs Claude Code headlessly in a loop for N iterations. Each iteration runs Claude with --output-format stream-json and saves the transcript as claude-iteration-N.jsonl. The loop handles rate-limit backoff, zombie task cleanup, and injects performance feedback from recent sessions into the next iteration's prompt.

• Beads (bd) — A git-native, CLI-first issue tracker that stores issues in .beads/issues.jsonl. The JSONL parser detects bead commands (bd update <id> --status in_progress, bd-finish.sh) to determine which task was worked on and whether the session committed code. Sessions that run bd-finish.sh (which does git commit + push + bead close) count as "completed."

• claude-iteration-N.jsonl files — Session transcripts produced by the ralph-wiggum loop. Each file contains the full JSONL stream of a Claude Code session: assistant turns, tool calls, results, usage/cost data. The log and backfill commands parse these files to extract efficiency metrics.

Without these systems in place, the log/backfill/status/analyze commands will have no data to work with. The improvement add/list/fix/search commands work standalone as a generic improvement tracker.

Quick Start

Run these commands via Bash to get the current state:

# Dashboard — recent sessions + targets
self-improvement/self-improvement status

# Deep analysis of last 10 sessions
self-improvement/self-improvement analyze --last 10

# Open improvements needing attention
self-improvement/self-improvement improvement list --status open

Available Commands

Command	Purpose
self-improvement/self-improvement status [--last N]	Dashboard with recent sessions, trends, target comparison
self-improvement/self-improvement analyze [--last N]	Deep analysis, stores results, compares to previous run
self-improvement/self-improvement targets	Show efficiency targets and last 5 sessions vs targets
self-improvement/self-improvement improvement list [--status open]	List improvement records
self-improvement/self-improvement improvement search <query>	Search improvements by keyword
self-improvement/self-improvement improvement add --title "..." --severity high|medium|low [--desc "..."] [--rec "..."] [--tags "..."]	Add new improvement
self-improvement/self-improvement improvement fix <ref_id> [--impact "..."]	Mark improvement as fixed with measured impact
self-improvement/self-improvement log <jsonl-file>	Parse one iteration JSONL file into DB
self-improvement/self-improvement backfill [--from N] [--to N]	Bulk-parse iteration files
self-improvement/self-improvement seed	Populate improvements table with historical R1-R14 records

Efficiency Targets

Metric	Target	Description
Completion rate	>=85%	Sessions that commit code
Narration-only turns	<20%	Assistant turns with no tool calls
Parallel tool calls	>10%	Turns with 2+ batched tool calls
Turns per session	<80	Hard budget from PROMPT.md

Workflow: Reviewing Loop Health

If the user passes $ARGUMENTS, run that as a subcommand. Otherwise:

1. Run self-improvement/self-improvement status to see the dashboard
2. Run self-improvement/self-improvement analyze --last 10 for trend analysis
3. Run self-improvement/self-improvement improvement list --status open for open issues
4. Present a concise summary: what's working, what's not, what to do next
5. If the user wants to add or fix an improvement, use the improvement add or improvement fix commands

Workflow: After a Batch of Loop Iterations

1. Run self-improvement/self-improvement backfill --from <start> --to <end> to ingest new data
2. Run self-improvement/self-improvement analyze --last <count> to analyze the batch
3. Compare against previous analysis (the tool does this automatically)
4. Review open improvements and update their status based on measured data
5. File new improvements if new patterns are discovered

Database Location

SQLite database at self-improvement/self-improvement.db. Created automatically on first use. Tables: sessions, improvements, analysis_runs.