session-reflection-analysis

The session-reflection-analysis skill acts as an introspective tool for developers using Claude Code. By processing local JSONL session logs stored in ~/.claude/projects/, this skill identifies recurring patterns of inefficiency—such as redundant file reading, incorrect tool sequencing, or context loss. It is designed for engineers who want to maintain high development velocity while staying within token budget constraints. Rather than manually parsing logs, the skill utilizes jq to generate a condensed summary of user requests, tool executions, and system responses, which is then analyzed by a specialized subagent to provide actionable, structural feedback.

• Automatically maps the current working directory to relevant Claude Code project logs.

• Uses high-performance jq filtering to condense session history by up to 98%, preserving critical context while discarding noise.

• Spawns an Explore subagent to detect patterns like wasted tokens, repeated mistakes, missing automation, and assumption-driven errors.

• Generates a structured markdown reflection document containing prioritized improvements, code snippets, and expected impact metrics.

• Provides a safe, human-in-the-loop review process by proposing improvements rather than executing them directly.

• To trigger the skill, simply ask to reflect on the session.

• Ensure jq is installed on your system (brew install jq or apt install jq).

• The skill requires access to ~/.claude/projects/ and will output analysis to /tmp/session-summary.jsonl.

• Use the generated proposals to update CLAUDE.md, create custom bash scripts in .claude/skills/, or define new slash commands to prevent future inefficiencies.

• Always review proposed changes before implementation to ensure they align with the project's specific coding standards and architectural requirements.

• The output includes detailed cost-benefit analysis for each suggestion, helping prioritize high-impact documentation updates or automation tasks.