session-scan

Compute deterministic metrics for sessions discovered via ccrider MCP.

STOP — Read Before Executing

NEVER call mcp__ccrider__get_session_messages in main context. Each response is 5-50KB of JSON. Fetching N sessions directly = context crash.

You MUST delegate all scoring to subagents. The main context only does: discovery, deduplication, subagent spawning, and result collection.

Requirements

Requires ccrider MCP. If not available:

ccrider MCP is required. See: https://github.com/neilberkman/ccrider

Usage

/session-scan                         # Last 7 days, up to 50 sessions
/session-scan --since 2026-02-01      # Since specific date
/session-scan --project enaia         # Filter by project name
/session-scan --limit 20              # Cap session count
/session-scan --list                  # Discovery only, no scoring
/session-scan --rescan                # Recompute already-scanned sessions

What Main Context Does

1. Parse Arguments

Extract from $ARGUMENTS:

• --since DATE: ISO date filter (default: 7 days ago)
• --project NAME: Filter by project path substring
• --limit N: Max sessions to process (default: 50)
• --list: Discovery only — show table, skip scoring
• --rescan: Recompute metrics for already-scanned sessions

2. Discover Sessions (safe — response is ~1KB)

mcp__ccrider__list_recent_sessions(limit: N, project: PROJECT, after_date: SINCE)

Filter out sessions with < 10 messages. If --list: show table and stop.

3. Deduplicate

Read .claude/session-metrics/metrics.jsonl (if exists). Skip sessions already scanned unless --rescan flag is set. Report: "N new sessions to scan (M already in ledger)"

4. Resolve Scorer Path

Glob: **/session-scan/references/compute-metrics.py

Store as SCORER_PATH (absolute). PROJECT_ROOT = current working directory.

5. Spawn ONE Subagent Per Session

DO NOT fetch messages yourself. DO NOT run Python yourself. You MUST use the Task tool to spawn subagents.

For EACH unscanned session, spawn a haiku subagent using this template:

Task(subagent_type="general-purpose", model="haiku", mode="bypassPermissions", prompt="""
Score one Claude Code session. Steps:

1. Fetch messages:
   mcp__ccrider__get_session_messages(session_id: "{SESSION_ID}", last_n: 200)

2. Write the full tool result (messages JSON) to:
   {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json

3. Run scorer and capture result in ONE Bash command:
   python3 {SCORER_PATH} {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json --session-id {SESSION_ID} --project {PROJECT_NAME} > {PROJECT_ROOT}/.claude/session-metrics/_result_{SHORT_ID}.json && rm {PROJECT_ROOT}/.claude/session-metrics/_tmp_{SHORT_ID}.json

4. Report back: "Scored {SHORT_ID}: friction=X.XX fingerprint=Y"

If ccrider fails, report the error and exit.
""")

Spawn ALL subagents in parallel. Wait for all to complete.

6. Collect Results

for f in .claude/session-metrics/_result_*.json; do
  cat "$f" >> .claude/session-metrics/metrics.jsonl
  rm "$f"
done

7. Display Results

Show summary table sorted by friction (descending):

| ID       | Project | Date       | Type        | Friction | Opportunity | Tier2? |
|----------|---------|------------|-------------|----------|-------------|--------|
| ffa155ee | enaia   | 2026-02-18 | bug-fix     | 0.42     | 0.65        | Yes    |
| 90a74843 | wedding | 2026-02-17 | feature     | 0.15     | 0.20        | No     |

If Tier 2 eligible: suggest /session-deep-dive --from-scan.

8. Update Scan Metadata

Write .claude/session-metrics/latest-scan.json:

{
  "scanned_at": "2026-02-20T14:30:00Z",
  "sessions_discovered": 25,
  "sessions_scanned": 18,
  "sessions_skipped": 7,
  "tier2_eligible": 5
}

Scoring Reference

See references/scoring-guide.md for full algorithm documentation.

• Friction Score (0-1): Weighted signals, sigmoid-normalized
• Fingerprint: Rule-based classifier (6 types)
• Plugin Opportunity (0-1): Missed /phx: commands
• Tier 2 Eligible: friction > 0.35 OR opportunity > 0.5 OR plugin used OR msgs > 50

Iron Laws

1. NEVER call get_session_messages in main context — WILL crash context
2. ONE subagent per session — each fetches exactly ONE session
3. mode="bypassPermissions" on every Task — subagents need Write+Bash
4. Absolute paths in subagent prompts — subagents don't inherit context
5. Result files, not direct append — avoid jsonl race conditions
6. NEVER modify existing metrics.jsonl entries — append-only ledger
7. ALWAYS delete temp and result files after processing