suggest

Session Review & Skill Synthesis

Review session logs for the current project to find recurring errors, friction points, and opportunities for improvement. Produces actionable recommendations: CLAUDE.md updates, new Skills, hooks, or code fixes.

Focus area (optional): If $ARGUMENTS is provided, narrow the review to that topic (e.g., "sql errors", "date assumptions", "slow queries"). Otherwise, perform a full review.

---

Step 0: Locate Session Logs

Session logs are JSONL files stored at:

~/.claude/projects/-{project-path-with-dashes}/

The project path is derived from the current working directory with / replaced by - and prefixed with -.

To find the session directory:

# Convert CWD to the Claude project path
PROJECT_DIR="$HOME/.claude/projects/-$(echo "$PWD" | tr '/' '-' | sed 's/^-//')"

To list sessions (most recent first):

ls -t "$PROJECT_DIR"/*.jsonl 2>/dev/null | head -20

Each JSONL file is one session. Each line is a JSON object with fields including:

• type: message type (human, assistant, tool_use, tool_result)
• message.role: user or assistant
• message.content: array of content blocks (text, tool_use, tool_result)

Important: Session files can be very large (10MB+). Use jq with streaming/filters rather than reading entire files into memory. Skip the current session's file (match by most recent modification time if needed).

---

Phase 1: Error Audit

Find all instances where code execution failed and required multiple attempts.

What to grep for in session JSONL files:

Failed bash commands — look for tool_result blocks containing error indicators:

# Count errors per session
for f in $(ls -t "$PROJECT_DIR"/*.jsonl | head -20); do
  errors=$(jq -r 'select(.message.content) | .message.content[] | select(.type == "tool_result" and .is_error == true) | .content' "$f" 2>/dev/null | wc -l)
  if [ "$errors" -gt 0 ]; then
    echo "$(basename "$f" .jsonl): $errors errors"
  fi
done

Common error patterns to search for:

• Traceback (most recent call last) — Python exceptions
• Error:, ERROR, error: — general errors
• command not found — missing tools/commands
• ModuleNotFoundError, ImportError — missing Python packages
• ConnectionRefusedError, OperationalError — database connection failures
• FileNotFoundError — wrong file paths
• AssertionError — assertion failures (e.g., load_dotenv() issues)
• SyntaxError — malformed code
• Permission denied — access issues

Identify retry sequences — look for the same tool being called multiple times in succession with similar content, where earlier calls failed:

# Extract tool_use + tool_result pairs to identify retries
jq -c 'select(.message.content) | .message.content[] | select(.type == "tool_use") | {tool: .name, id: .id}' "$SESSION_FILE" 2>/dev/null

Output for Phase 1:

Create a table:

Error Category	Frequency (sessions)	Example Error	Session ID(s)

---

Phase 2: Friction Analysis

Beyond outright errors, identify patterns of wasted effort:

Incorrect assumptions

• Date/year confusion: grep for hardcoded years like 2024, 2025 in assistant messages that were corrected
• Wrong file paths: tool_result errors with FileNotFoundError or No such file
• Wrong data formats: mismatched column names, wrong date formats, incorrect JSON structure

Repeated lookups

• Same Grep or Glob queries appearing across multiple sessions
• Same file being Read at the start of many sessions
• Questions about CLI syntax, table schemas, or configuration that could be pre-loaded

Ad-hoc scripts written multiple times

• Similar Python/bash snippets appearing across sessions with slight variations
• Data analysis patterns that get reinvented each time

Inconsistent approaches

• Same task done differently across sessions (e.g., different SQL patterns, different analysis methods)
• Contradictory conclusions from similar analyses

Output for Phase 2:

Bulleted list of friction points with session references:

• [Category]: Description — sessions: abc123, def456

---

Phase 3: Solution Triage

For each error category and friction point, recommend the most appropriate fix:

Fix Type	When to Use	Example
CLAUDE.md update	Guidance, constraints, awareness needed at session start	"Always use lagged data for predictions"
Claude Code Skill	Structured, reusable pattern with specific steps/templates	db-query skill with connection template
Helper script/CLI	Reusable code that eliminates manual steps	trader review-universe command
Hook	Automated validation on every tool use	check-python-env.py pre-run hook
Code fix	The underlying code is wrong or fragile	Fix function to handle edge case

Decision criteria:

• If the fix is awareness/context → CLAUDE.md
• If the fix is a repeatable procedure with specific steps → Skill
• If the fix is automated validation → Hook
• If the fix is a reusable script → Helper/CLI command
• If the fix is a bug in the codebase → Code fix

---

Phase 4: Prioritised Recommendations

Rank recommendations by: (frequency of error) × (token cost per occurrence) × (ease of fix)

Scoring guide:

• Frequency: 1 (rare) to 5 (every session)
• Token cost: 1 (quick fix) to 5 (hundreds of lines of retries)
• Ease of fix: 5 (trivial) to 1 (major refactor)
• Priority score = Frequency × Token Cost × Ease

Present as a table:

Priority	Score	Problem	Frequency	Token Cost	Ease	Fix Type	Description
1	125	SQL connection failures	5	5	5	Skill	db-query skill with connection template
2	...	...	...	...	...	...	...

---

Phase 5: Draft Artifacts

For the top 3-5 recommendations, draft ready-to-commit content:

For CLAUDE.md updates:

• Draft the exact text to add/modify
• Specify where in CLAUDE.md it should go (section heading)
• Keep additions concise — CLAUDE.md bloat degrades context window

For new Skills:

• Draft the full SKILL.md with YAML frontmatter
• Follow the structure: frontmatter → overview → steps → templates → examples
• Use allowed-tools to restrict to minimum necessary tools
• Set disable-model-invocation: true for user-invoked skills

For hooks:

• Draft the hook script
• Specify the event type (PreToolUse, PostToolUse, etc.)
• Include the settings.json configuration

For code fixes:

• Identify the exact file and function to change
• Describe the fix but do NOT make the change — present it for user approval

---

Phase 6: CLAUDE.md Health Check

Review the current project's CLAUDE.md for:

Outdated references

• File paths that no longer exist
• Thresholds or values that have changed
• Features that were removed or renamed
• Dependencies that were added or removed

Bloat

• Sections that could be compressed without losing context
• Duplicate information
• Overly verbose explanations that could be tables
• Content that belongs in a Skill rather than CLAUDE.md

Missing sections

• Error patterns from Phase 1 that have no corresponding guidance
• Friction points from Phase 2 that need awareness
• Project conventions that are followed but not documented

Consistency

• Does CLAUDE.md match the actual codebase structure?
• Are file paths and command examples still correct?
• Do referenced tools/commands still exist?

---

Output Format

Structure your final output as:

1. Error Audit Summary

Table of error categories with frequencies and example session IDs.

2. Friction Points

Bulleted list with session references.

3. Prioritised Recommendations

Ranked table with scores.

4. Draft Artifacts

Ready-to-commit CLAUDE.md updates, Skills, hooks — each in a fenced code block with the target file path.

5. CLAUDE.md Health Report

Outdated items, bloat candidates, missing sections, consistency issues.

---

Tips for Efficient Log Parsing

• Start with recent sessions — they reflect current codebase state
• Use jq filters — don't read entire JSONL files as text
• Sample first — check 5-10 sessions before doing a full sweep
• Skip very short sessions — sessions under 10 lines are usually aborted
• Focus on assistant tool_use → tool_result pairs — this is where errors surface
• Count, don't quote — summarise error patterns rather than pasting full tracebacks
• If $ARGUMENTS is set, filter to only that topic area to stay focused