Evaluation: Rob Zolkos - Deep Dive: How Claude Code's /insights Command Works

Evaluation: Rob Zolkos - Deep Dive: How Claude Code's /insights Command Works

Resource Type: Blog Article (Technical Deep Dive) Author: Rob Zolkos (@zolkos) Date: 2026-02-04 URL: https://www.zolkos.com/2026/02/04/deep-dive-how-claude-codes-insights-command-works.html Evaluation Date: 2026-02-06 Evaluator: Claude Sonnet 4.5

1. Content Summary

Technical deep dive documenting the architecture and implementation of Claude Code's /insights command. Comprehensive coverage of the analysis pipeline, facets classification system, and technical specifications.

Key Content:

• 7-stage analysis pipeline (session filtering → transcript summarization → facet extraction → aggregated analysis → executive summary → report generation)
• Facets classification system (13 goal types, 6 satisfaction levels, 4 outcome states, 12 friction types, 5 helpfulness scale, 5 session types, 7 success categories)
• Technical specifications (Claude Haiku, 8,192 max tokens, 50 sessions per run, caching system, storage locations)
• Analysis features (repeated instructions detection, pattern identification, feature recommendations)
• Privacy & performance (local analysis, facet caching, code pattern focus vs content)

Depth: ~1,500 words, technical specification level (not user tutorial)

2. Initial Scoring: 4/5 (High Value)

Justification

Points forts:

• ✅ Comprehensive technical architecture - 7-stage pipeline fully documented
• ✅ Facets system detailed - All classification categories enumerated (13 goals, 12 friction types, 7 success categories)
• ✅ Actionable specifications - Storage paths, model details, token limits, caching behavior
• ✅ Implementation depth - Explains chunking (25K chars), filtering rules (min 2 messages, 1 min duration), caching strategy
• ✅ Fills major guide gap - /insights was completely undocumented before this
• ✅ Source credibility - Technical deep dive, not marketing content

Comparaison avec post Kajan:

• Post Kajan (2/5): "ça existe, teste-le" = 0% technique
• Deep dive Zolkos (4/5): Pipeline + facets + specs + caching = 95% technique

Pourquoi 4/5 et pas 5/5:

• ❌ Pas de screenshots du rapport HTML (décrit mais pas montré)
• ❌ Pas d'exemples de prompts utilisés pour l'analyse
• ❌ Pas de guidance utilisateur (comment interpréter le rapport, quelles actions prendre)
• ❌ Aucune mention de limitations ou edge cases
• ⚠️ Discrepancy: Says "max 4,096 output tokens" in Stage 3 but "8,192 max tokens" in specs (need to verify which is correct)

Score 4/5 = High value technical resource qui mérite intégration rapide, mais pas critique (5/5) car manque guidance utilisateur et exemples visuels.

3. Comparative Analysis

Comparison avec notre guide (v3.23.1, post-documentation)

Complémentarité:

• Zolkos = Architecture interne (pipeline, facets, caching)
• Notre guide = Usage externe (how to, when, interpret, integrate)
• Ensemble = Documentation complète (architecture + pratique)

4. Fact-Check

Corrections needed:

• ⚠️ Token limit discrepancy (4,096 vs 8,192) — Need to verify which is correct
  • Stage 3: "Claude Haiku (max 4,096 output tokens)"
  • Technical Specifications: "Max tokens per prompt: 8,192"
  • Hypothesis: 8,192 INPUT tokens, 4,096 OUTPUT tokens (standard Haiku limits)

5. Technical Challenge (by technical-writer agent)

Challenge Questions

Q1: "Score 4/5 pour un article technique complet sur un sujet non-documenté. Pourquoi pas 5/5?"

A1: Distinction entre architecture interne vs impact utilisateur:

• Architecture (Zolkos): 95% complet (pipeline, facets, specs)
• User value (manquant): 0% guidance pratique (comment interpréter, quelles actions, quand l'utiliser)
• Score 5/5 nécessite: Technical depth + Actionable guidance + Visual examples
• Score 4/5 = Excellent technical documentation mais manque couche pratique

Analogie: C'est comme avoir les specs PostgreSQL (excellent) sans guide "How to optimize your queries" (manquant).

Q2: "Le guide documente déjà /insights après notre travail. La valeur de Zolkos n'est-elle pas réduite?"

A2: Non, complémentarité forte:

Valeur ajoutée: Permet aux power users de comprendre:

• Pourquoi certaines sessions sont exclues (min 2 messages, 1 min)
• Comment optimiser pour meilleure analyse (éviter sessions <2 messages)
• Quelles catégories de friction sont trackées (12 types → savoir lesquelles éviter)
• Pourquoi le rapport est rapide après première run (facet caching)

Q3: "Devrait-on intégrer toute l'architecture dans le guide ou juste référencer Zolkos?"

A3: Hybrid approach optimal:

À intégrer dans le guide:

• ✅ Facets categories (13 goals, 12 friction types) → Aide interprétation rapport
• ✅ Session filtering rules (min 2 messages, 1 min) → Explique pourquoi sessions manquantes
• ✅ Caching behavior → Explique pourquoi 2e run rapide
• ✅ Storage structure (facets/, report.html) → Troubleshooting

À référencer comme source externe:

• Pipeline stages 1-7 (détail implémentation) → Trop technique pour guide utilisateur
• Transcript chunking logic → Implementation detail
• Model prompts → Proprietary/complex

Format recommandé:

### How /insights Works (Architecture Overview)

The analysis uses a 7-stage pipeline (detailed in [Zolkos deep dive](url)):
1. Session filtering (min 2 messages, 1 min duration)
2. Transcript summarization (25K char chunks)
3. Facet extraction (13 goal types, 12 friction types)
4. Aggregated analysis across sessions
5. Executive summary generation
6. Interactive HTML report

**Facets tracked**:
- Goals (13): Debug, Implement Feature, Fix Bug, Write Script, [...]
- Friction (12): Buggy code, wrong approach, misunderstood requests, [...]
- Satisfaction (6): Frustrated → Dissatisfied → Likely Satisfied → Satisfied → Happy
- Outcomes (4): Not Achieved → Partially → Mostly → Fully Achieved

Results cached in `~/.claude/usage-data/facets/` for fast subsequent runs.

Source: [Zolkos Technical Deep Dive](url)

Q4: "Discrepancy 4,096 vs 8,192 tokens — Impact sur la documentation?"

A4: Clarification nécessaire:

• Hypothesis probable: 8,192 INPUT tokens, 4,096 OUTPUT tokens (Haiku standard)
• Impact guide: Documenter "up to 8,192 tokens per analysis pass" (INPUT)
• Action: Vérifier dans CHANGELOG officiel Claude Code ou tester empiriquement

Pas bloquant: La valeur reste identique (architecture compréhensible), juste précision à affiner.

Adjusted Score After Challenge

Score maintenu: 4/5 (High Value)

Rationale confirmée:

• Architecture technique excellente (95% complet)
• Complémentaire avec notre doc utilisateur
• Manque guidance pratique + screenshots pour 5/5
• Discrepancy tokens mineure (clarifiable)

6. Integration Decision

Decision: INTEGRATE ✅ (avec hybrid approach)

Rationale:

1. Fills architecture gap - Notre doc explique usage, Zolkos explique fonctionnement interne
2. Power user value - Comprendre facets → optimiser workflows pour meilleure analyse
3. Troubleshooting aid - Session filtering rules expliquent pourquoi certaines sessions absentes
4. Credible source - Technical deep dive, pas marketing fluff
5. Complementary not redundant - Architecture (Zolkos) + Usage (notre guide) = complet

Integration Strategy

Phase 1: Architecture Overview dans guide (< 1 week)

Ajouter sous-section "How /insights Works" dans Section 6.1:

### How /insights Works (Architecture Overview)

The analysis pipeline processes session data through 7 stages:

1. **Session Filtering**: Loads from `~/.claude/projects/`, excludes agent sub-sessions, <2 messages, <1 min duration
2. **Transcript Summarization**: Chunks sessions >30K chars into 25K segments
3. **Facet Extraction**: Uses Claude Haiku to classify sessions into structured categories
4. **Aggregated Analysis**: Cross-session pattern detection
5. **Executive Summary**: "At a Glance" synthesis
6. **Report Generation**: Interactive HTML with visualizations
7. **Facet Caching**: Saves to `~/.claude/usage-data/facets/<session-id>.json` for fast subsequent runs

**Facets Classification System**:

The system categorizes sessions using:

**Goals (13 types)**:
Debug/Investigate, Implement Feature, Fix Bug, Write Script/Tool, Refactor Code,
Configure System, Create PR/Commit, Analyze Data, Understand Codebase, Write Tests,
Write Docs, Deploy/Infra, Cache Warmup

**Friction Types (12 categories)**:
Misunderstood requests, Wrong approach, Buggy code, User rejected actions,
Claude blocked, Early user stoppage, Wrong file locations, Over-engineering,
Slowness/verbosity, Tool failures, Unclear requests, External issues

**Satisfaction Levels (6)**:
Frustrated → Dissatisfied → Likely Satisfied → Satisfied → Happy → Unsure

**Outcomes (4)**:
Not Achieved → Partially Achieved → Mostly Achieved → Fully Achieved

**Success Categories (7)**:
Fast accurate search, Correct code edits, Good explanations, Proactive help,
Multi-file changes, Good debugging, None

**Session Types (5)**:
Single task, Multi-task, Iterative refinement, Exploration, Quick question

**Technical Specifications**:
- Model: Claude Haiku
- Max tokens: 8,192 per analysis pass
- Sessions analyzed: Up to 50 new sessions per run
- Storage: `~/.claude/usage-data/report.html` + `facets/` cache directory
- Performance: Facet caching ensures incremental analysis (only new sessions)

Understanding these categories helps interpret the report:
- High "Buggy code" friction → Implement pre-commit hooks
- Low satisfaction on "Implement Feature" → Improve planning phase
- "Early user stoppage" pattern → Check if requests too vague

**Source**: [Zolkos Technical Deep Dive](https://www.zolkos.com/2026/02/04/deep-dive-how-claude-codes-insights-command-works.html)

Phase 2: Reference dans Troubleshooting (optionnel)

Ajouter FAQ:

**Q: Why are some of my sessions missing from /insights?**

A: The analysis filters out:
- Agent sub-sessions (Task tool invocations)
- Sessions with <2 user messages
- Sessions <1 minute duration
- Internal operations

This focuses the report on meaningful interactions. To ensure sessions are included, avoid extremely short exchanges.

Phase 3: Update resource evaluation index

| **Zolkos** (/insights deep dive) | 4/5 | **4/5** | ✅ Integrated (architecture section) | [zolkos-insights-deep-dive.md](./zolkos-insights-deep-dive.md) |

7. Implementation Notes

What to integrate

High priority (do now):

• ✅ Facets categories (all 6 classification systems)
• ✅ Session filtering rules (min 2 messages, 1 min)
• ✅ Storage paths + caching behavior
• ✅ Technical specs (Haiku, 8192 tokens, 50 sessions)
• ✅ Source attribution with link

Medium priority (later):

• Pipeline stages overview (simplified)
• Troubleshooting FAQ (why sessions excluded)

Low priority (reference only):

• Stage-by-stage implementation details
• Prompt engineering specifics
• Transcript chunking algorithm

Where to integrate

Primary location: Section 6.1 "The /insights Command"

• Add new subsection "### How /insights Works (Architecture Overview)"
• Insert after "#### Technical Details" subsection
• Before "#### Limitations" subsection

Secondary mentions:

• Section 9 (Troubleshooting): FAQ about missing sessions
• machine-readable/reference.yaml: Add facets categories as reference

Token budget estimate

Integration adds ~800 tokens to guide (facets tables + architecture overview).

Trade-off acceptable: Architecture transparency > brevity for power user command.

8. Related Resources

9. Final Metadata

Initial Score: 4/5 Final Score: 4/5 Decision: Integrate ✅ Confidence: High

Integration Timeline:

1. ✅ Evaluation complete (2026-02-06)
2. ⏳ Add architecture overview to guide (< 1 week)
3. ⏳ Update resource evaluation index
4. ⏳ Optional: FAQ in troubleshooting

Next Actions:

1. ✅ Evaluation documented
2. ⏳ Integrate facets + architecture in Section 6.1
3. ⏳ Verify token discrepancy (4,096 vs 8,192)
4. ⏳ Check CHANGELOG for /insights release version

Archive Location: docs/resource-evaluations/zolkos-insights-deep-dive.md

Evaluation complete: 2026-02-06

Attribution: Rob Zolkos, zolkos.com