Agent Skills: CC Sessions Review

CC Sessions Review

Analyze Claude Code session history using compound engineering principles. Identify anti-patterns, missed compounding opportunities, verification gaps, and undocumented knowledge. Produce actionable recommendations with implementation-ready drafts.

Instructions

Step 1: Resolve Scope

If $ARGUMENTS already includes scope information, use it directly and skip interactive scope questions.

If no scope argument is provided, ask scope at the start using AskUserQuestion:

1. Project scope:
   • Current project
   • All projects
2. Timeframe:
   • current
   • today
   • week
   • month
   • last-N

If user selects last-N, ask one follow-up question for N (number only), then build last-N.

Convert answers to script args:

• Current project + timeframe: SCOPE_ARGS="<timeframe>"
• All projects + timeframe: SCOPE_ARGS="--all-projects <timeframe>"

Step 1.5: Discover Sessions

Run the discovery script with resolved scope:

bash ./skills/cc-sessions-review/scripts/discover_sessions.sh $SCOPE_ARGS

Analysis time scales with session count and session size. For week/month/--all-projects, prioritize substantial sessions first, then summarize short sessions. If scope is large, state the estimated review depth before continuing.

Available scopes: current, today, week, month, last-N (e.g., last-5). Use --all-projects to include all ~/.claude/projects/* session directories.

If no sessions are found, inform the user and suggest checking the project path.

Step 2: Parse Conversations, Compute Session Stats, Detect Skill Usage

For each discovered session file, extract the conversation using jq.

Extract user messages (skip system messages starting with <system):

jq -r 'select(.type == "user" and .userType == "external") | .message.content | if type == "string" then . elif type == "array" then [.[] | select(.type == "text") | .text] | join("\n") else empty end' SESSION_FILE

Extract assistant responses with tool usage:

jq -c 'select(.type == "assistant") | {text: [.message.content[]? | select(.type == "text") | .text] | join("\n"), tools: [.message.content[]? | select(.type == "tool_use") | .name]}' SESSION_FILE

Compute per-session stats (ID, date, size, turns, tool calls, tools used) using the commands in:

• references/session-parsing.md → Per-Session Stats

Classify each session:

• Substantial: USER_TURNS > 5 OR SIZE_BYTES > 51200 (50KB)
• Short: not substantial
• Abandoned: last external user turn has no following assistant turn, or user explicitly aborts (never mind, skip this, stop, forget it)

Build a session-level table row for each file:

• ID
• Date
• User turns
• Assistant turns
• Tools used
• Size (KB)
• Class (Substantial/Short/Abandoned)

Track totals for:

• Sessions analyzed
• Substantial sessions
• Short sessions
• Abandoned sessions

Detect skill invocations (store for Step 6 validation):

# Extract skill names used in this session
bash ./skills/cc-sessions-review/scripts/extract_used_skills.sh SESSION_FILE

This detects skills invoked via /skill-name pattern in user messages. Store the results to check against recommendations in Step 6.

CRITICAL: For large sessions, use this 3-step chunk workflow and synthesize at the end:

1. Check size:

LINES="$(wc -l < "$SESSION_FILE" | tr -d ' ')"
echo "Total lines: $LINES"

2. Chunk with offset windows:

CHUNK=200
OFFSET=0
while [ "$OFFSET" -lt "$LINES" ]; do
  tail -n +"$((OFFSET + 1))" "$SESSION_FILE" | head -n "$CHUNK" > "/tmp/session-${SESSION_ID}-${OFFSET}.jsonl"
  # analyze each chunk independently before moving on
  OFFSET=$((OFFSET + CHUNK))
done

3. Synthesize:

• Merge chunk-level findings into one per-session summary.
• De-duplicate repeated issues across chunks before scoring/recommending.

See references/session-parsing.md for full JSONL format details and additional extraction patterns.

Step 3: Check Codebase Context

Before analyzing, gather project context to make recommendations specific.

Extract skill and configuration context (store for Step 6 validation):

# Get installed skills, CLAUDE.md status, and agents.md detection
bash ./skills/cc-sessions-review/scripts/extract_skill_context.sh .

This returns JSON with:

• installed_skills[] - names of all installed skills
• has_claude_md - whether CLAUDE.md exists
• has_agents_md - whether agents.md exists
• agents_md_path - path to agents.md if found

Additional context:

• Read CLAUDE.md if it exists (check project root and .claude/ directory)
• List commands: ls commands/*.md 2>/dev/null
• Check docs structure: ls docs/ 2>/dev/null
• Check for hooks configuration

This context determines what already exists vs. what to recommend creating.

Step 4: Analyze Patterns

Apply the six detection categories from references/compound-engineering-principles.md:

1. Compounding patterns - Repeated problems, unextracted patterns, missed reuse, no automation
2. Verification gaps - User caught issues agent could have detected, including friction signals
3. Documentation gaps - Undocumented patterns, procedures, best practices
4. Delegatable work - Manual tasks suitable for agent delegation
5. Stage progression - Always report stage indicators and evidence
6. Planning/work balance - Always report turn ratios and evidence

For Verification Gaps, always compute friction signals:

• Correction keyword count (no, that's wrong, actually, doesn't work, broke)
• Topic loops: 5+ turns stuck on same issue/topic
• Abandoned thread count
• Undo/revert pattern count (undo, revert, roll back, start over)

For Stage Progression, always show:

• Inferred current stage
• Evidence counts supporting that stage
• Next-stage indicator (or explicitly state current stage is appropriate now)

For Planning/Work Balance, always show:

• Turn counts and ratios for Planning, Work, Review, Compound
• Whether ratio is healthy or imbalanced

For each finding, record:

• Category
• Evidence (specific quotes or turn references from the session)
• Impact (high/medium/low)
• Concrete recommendation

Step 5: Generate Report

Present findings in this order:

1. Session Overview (always first):

## Session Overview
Sessions analyzed: N (Substantial: N | Short: N | Abandoned: N)

| Session ID | Date | User turns | Assistant turns | Tools used | Size | Class | Quality (1-10) |
|---|---|---:|---:|---|---:|---|---:|
| ... | ... | ... | ... | ... | ...KB | Substantial | 7.8 |

Quality score formula (per session, clamp to 1-10):

quality = clamp(1, 10,
  5.0
  - 0.6 * correction_count
  - 1.2 * topic_loop_count
  - 1.0 * abandoned_count
  - 0.8 * undo_revert_count
  + 0.9 * compound_actions
  + 0.5 * documented_patterns
  - 2.0 * abs(planning_ratio - 0.80)
)

Where:

• compound_actions = number of compounding outputs in session (new/updated skill, automation script/hook, durable docs update such as CLAUDE.md).
• documented_patterns = repeated conventions/procedures captured into durable docs during or from the session.
• planning_ratio = planning_turns / (planning_turns + work_turns + review_turns + compound_turns) (use 0 if denominator is 0).

2. Summary (always show):

## Session Review: [scope]
Sessions analyzed: N | Turns: N user, N assistant

### Top Recommendations
1. [Highest impact finding + action]
2. [Second highest]
3. [Third highest]

3. Detailed Breakdown (show after summary):

Show all six categories every time (never skip categories).

For each category:

• Category heading with count (or 0 critical findings)
• Metrics and evidence (always include data)
• Findings with short evidence quotes
• Specific recommendation or explicit "healthy" note backed by metrics

Under Verification Gaps, include:

• ### Friction Points
• Correction count, loop count, abandoned/undo counts, and why they matter

Do not output bare "No issues detected" without supporting data.

CRITICAL: Keep evidence quotes short (1-2 sentences). Do not reproduce entire conversation turns.

Step 6: Offer Implementation Plan

VALIDATION BEFORE PRESENTING RECOMMENDATIONS:

Before presenting recommendations, validate against existing codebase (using data from Steps 2-3):

1. Check for agents.md symlink opportunity:

   • If has_claude_md == false AND has_agents_md == true
   • Prepend recommendation: "Create symlink for CLAUDE.md compatibility: ln -s <agents_md_path> <target_location>"
   • Explain: Claude Code looks for CLAUDE.md. Symlinking from agents.md ensures compatibility without duplication.

2. Validate skill recommendations against existing skills:

   • For each skill recommendation, extract the suggested skill name
   • Check if name exists in:
     • installed_skills[] from Step 3
     • Skills detected in Step 2 (used in session)
   • If skill exists: Change recommendation to "Enhance existing skill: [name]" + describe what functionality to add
   • If skill doesn't exist: Proceed with "Create new skill: [name]" recommendation

After presenting the validated report, use AskUserQuestion to ask which recommendations to implement:

Which recommendations should I create an implementation plan for?
Options:
1. [Recommendation 1 summary]
2. [Recommendation 2 summary]
3. [Recommendation 3 summary]
4. All recommendations

For selected recommendations, generate a concrete plan where every recommendation includes:

• What to create/update
• Where it goes (exact path)
• Estimated size (e.g., "~20 lines", "~1 file + 1 config update")

Use these output requirements:

• agents.md symlink: Show exact command with full paths
• CLAUDE.md additions: Include exact draft text in a fenced code block
• Skill creation: If new, include folder path and SKILL.md skeleton frontmatter:

  ---
  name: <skill-name>
  description: <what it does + trigger conditions>
  ---
  

• Skill enhancement: Specify exact sections to add/change in existing SKILL.md
• Script/hook automation: Provide exact script/hook path and starter command/body
• Permission changes: Specify exact permission(s) to grant and why

Examples

Example 1: Review Today's Sessions

User says: /cc-sessions-review today

Actions:

1. Use provided scope argument (skip AskUserQuestion)
2. Run discover_sessions.sh today to find today's session files
3. Parse each session, compute stats table rows, classify substantial/short/abandoned
4. Check codebase for CLAUDE.md, skills, docs
5. Analyze across all six categories, including friction signals
6. Generate session overview + summary + detailed breakdown (all categories)
7. Ask which recommendations to implement

Result: Report showing e.g., "User corrected browser rendering issues 3 times - agent lacked browser verification. Recommend granting Playwright MCP access and adding a frontend verification step."

Example 2: Review Last 5 Sessions

User says: /cc-sessions-review last-5

Actions:

1. Use provided scope argument (skip AskUserQuestion)
2. Discover 5 most recent sessions
3. Parse, classify sessions, and analyze across sessions
4. Focus on patterns that repeat across sessions, not within a single one

Result: Report showing e.g., "Same database query pattern explained in 3 of 5 sessions. Recommend adding to CLAUDE.md: 'Always use the repository pattern for DB access, see src/repos/'"

Example 3: Interactive Scope Selection

User says: /cc-sessions-review

Actions:

1. Ask project scope (current/all)
2. Ask timeframe (current/today/week/month/last-N)
3. Build SCOPE_ARGS and run discovery script
4. Continue with normal parse/analyze/report flow

Sample Output

## Session Overview
Sessions analyzed: 4 (Substantial: 2 | Short: 1 | Abandoned: 1)

| Session ID | Date | User turns | Assistant turns | Tools used | Size | Class | Quality (1-10) |
|---|---|---:|---:|---|---:|---|---:|
| 84a7e050... | 2026-02-11 14:20 | 18 | 21 | Read,Bash,Edit | 96KB | Substantial | 6.4 |
| c51b1fd2... | 2026-02-11 09:07 | 7 | 8 | Read,Bash | 33KB | Substantial | 8.1 |
| 19dd30c0... | 2026-02-10 17:44 | 3 | 3 | Read | 11KB | Short | 7.9 |
| 33ae8b2e... | 2026-02-10 11:06 | 5 | 4 | Read,Bash | 20KB | Abandoned | 4.8 |

## Session Review: week
Sessions analyzed: 4 | Turns: 33 user, 36 assistant

### Top Recommendations
1. Add frontend verification workflow (Playwright screenshot + console check) before marking UI tasks complete.
2. Capture repeated repository-pattern guidance in CLAUDE.md under "Database Access".
3. Create a `release-checklist` skill to standardize pre-release checks.

## Detailed Breakdown

### 1. Compounding Patterns (2 findings)
- Metrics: repeated DB pattern explanation in 3 sessions; same release checks run manually in 2 sessions.
- Evidence: "Use repository pattern for DB access" repeated across 3 session IDs.
- Recommendation: document DB rule in CLAUDE.md; automate release checks in a skill.

### 2. Verification Gaps (1 critical finding)
- Metrics: correction_count=4, topic_loops=1, abandoned=1, undo/revert=1.
- Evidence: user reported browser regression after implementation with no browser validation step.
- Recommendation: add verification gate with Playwright MCP and test command checklist.

### Friction Points
- Corrections: 4 (high), Loops: 1 (moderate), Abandoned: 1 (moderate), Undo/Revert: 1 (moderate).
- Why it matters: repeated rework suggests missing upfront verification and weak acceptance checks.

### 3. Documentation Gaps (1 finding)
- Metrics: 2 conventions repeated, 0 captured in docs.
- Evidence: naming and DB guidance repeated without durable documentation.
- Recommendation: add CLAUDE.md section with exact conventions.

### 4. Delegatable Work (1 finding)
- Metrics: manual log parsing done in 2 sessions by user copy/paste.
- Evidence: user pasted repeated command output instead of delegating.
- Recommendation: have agent run parsing commands directly and summarize.

### 5. Stage Progression
- Inferred stage: Stage 2 (agentic tools + close supervision).
- Evidence: direct implementation requests=9, review turns=3, planning turns=4, compound turns=2.
- Next-stage indicator: enough repeated flow to pilot a plan-first workflow in similar tasks.

### 6. Planning/Work Balance
- Turn ratios: Planning 11%, Work 63%, Review 18%, Compound 8%.
- Assessment: imbalanced toward direct work relative to 80/20 guidance.
- Recommendation: add a short planning phase and explicit verification checklist before implementation.

Additional Resources

• references/compound-engineering-principles.md - Detection algorithms, signal thresholds, recommendation types for all six categories
• references/session-parsing.md - JSONL format, jq extraction patterns, content type handling
• scripts/discover_sessions.sh - Session file discovery with scope filtering (--all-projects support)