cc-sessions-review

What this skill does

# 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
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`):
```bash
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:
```bash
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):
```bash
# 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:
```bash
LINES="$(wc -l < "$SESSION_FILE" | tr -d ' ')"
echo "Total lines: $LINES"
```
2. Chunk with offset windows:
```bash
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):
```bash
# 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):
```markdown
## 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):
```text
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 co