docs: integrate /insights architecture from Zolkos deep dive (4/5)
1. Resource evaluation (docs/resource-evaluations/zolkos-insights-deep-dive.md):
- Score: 4/5 (High Value) - comprehensive technical architecture
- Content: 7-stage pipeline, facets classification (6 dimensions), technical specs
- Decision: Integrate architecture + facets (complementary with usage doc)
- Comparison: Zolkos (architecture interne) vs Guide (usage externe) = complet
- Why not 5/5: Missing user guidance, screenshots, prompt examples
- Updated index: 23 evaluations total
2. Architecture Overview added to guide (ultimate-guide.md L6460+):
- 7-stage pipeline: filtering, summarization, facet extraction, aggregation,
executive summary, report generation, facet caching
- Facets Classification System (6 dimensions):
* Goals (13 types): Debug, Implement, Fix Bug, Write Script, Refactor, etc.
* Friction (12): Misunderstood, wrong approach, buggy code, user rejection, etc.
* Satisfaction (6): Frustrated → Dissatisfied → Likely → Satisfied → Happy
* Outcomes (4): Not → Partially → Mostly → Fully Achieved
* Success (7): Fast search, correct edits, explanations, proactive, multi-file, etc.
* Session Types (5): Single, multi, iterative, exploration, quick question
- Performance: Caching system (facets/<session-id>.json) for incremental analysis
- Interpretation guidance: How facets help understand report recommendations
- Source attribution: Zolkos Technical Deep Dive (2026-02-04)
3. CHANGELOG [Unreleased]:
- Comprehensive /insights documentation with architecture deep dive
- Facets classification system (6 dimensions documented)
- Performance optimization explanation (caching)
- Resource evaluation: Zolkos deep dive (4/5, integrated)
Impact: Power users can now understand WHY /insights generates specific suggestions
(based on facets classification), optimize workflows for better analysis (avoid <2 msg
sessions), and interpret friction categories with context (12 types documented).
Complementarity proven: Usage documentation (existing) + Architecture (Zolkos) = complete.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
bd01add3f6