analyzing-kb-gaps

name	analyzing-kb-gaps
description	Use when you have Knowledge Base exports and want to identify user pain points, missing articles, and AI assistance opportunities.

Analyzing KB Gaps

Overview

Uses the Knowledge Base as a proxy for where users struggle. Identifies high-volume topics, missing guidance, and opportunities for better self-service or AI-assisted resolution.

When to Use

• Have KB article exports to analyze
• Want to understand what users struggle with most
• Exploring AI assistant opportunities
• Planning documentation improvements

Core Pattern

Step 1: Gather Sources

Read files in:

• inputs/knowledge_base/ - KB article exports
• outputs/insights/voc-synthesis-*.md - VOC insights (if available, for correlation)

Step 2: Analyze Article Coverage

For each KB article (or category), note:

• Topic / Category
• Article count
• Last updated date
• Estimated complexity (simple how-to vs. complex troubleshooting)

Step 3: Identify Gaps

Look for:

1. High-volume topics - Many articles = users struggle here
2. Outdated articles - Not updated in 6+ months
3. Missing topics - VOC mentions issues with no KB coverage
4. Complex troubleshooting - Multi-step processes that could be simplified

Step 4: Assess AI Opportunities

For each gap, evaluate:

Opportunity Type	Criteria	Risk Level
Better search/IA	Hard to find articles	Low
Guided resolution	Multi-step process	Low-Medium
AI-assisted	Can be automated with citations	Medium
DO NOT automate	Compliance, billing, trust-sensitive	High

Step 5: Generate Output

Write to outputs/insights/kb-gaps-YYYY-MM-DD.md:

---
generated: YYYY-MM-DD HH:MM
skill: analyzing-kb-gaps
sources:
  - inputs/knowledge_base/*.md
  - outputs/insights/voc-synthesis-*.md (if used)
downstream:
  - outputs/roadmap/Qx-YYYY-charters.md
---

# KB Gap Analysis: [Date]

## Executive Summary
[2-3 sentences: What's the state of KB? Where are the biggest gaps?]

## Coverage Overview

| Category | Article Count | Last Updated | Complexity | Gap Score |
|----------|---------------|--------------|------------|-----------|
| [Category 1] | N | YYYY-MM-DD | Simple/Complex | High/Med/Low |
| ... | ... | ... | ... | ... |

## High-Volume Topics
*Categories with most articles (signal: users struggle here)*

| Topic | Article Count | Sample Titles | VOC Correlation |
|-------|---------------|---------------|-----------------|
| [Topic] | N | [title1, title2] | [Yes/No/Unknown] |

## Missing / Outdated Articles

| Gap | Type | Evidence | Priority |
|-----|------|----------|----------|
| [Topic with no article] | Missing | VOC mentions in [file] | High |
| [Article X] | Outdated | Last updated [date] | Medium |

## AI Opportunity Assessment

### Safe to Automate (Low Risk)
| Opportunity | Type | Rationale |
|-------------|------|-----------|
| [Better search for X] | Search/IA | Articles exist but hard to find |
| [Guided wizard for Y] | Guided resolution | Clear steps, no judgment needed |

### Automate with Caution (Medium Risk)
| Opportunity | Type | Guardrails Needed |
|-------------|------|-------------------|
| [AI assist for Z] | AI-assisted | Must cite source article, human review |

### DO NOT Automate (High Risk)
| Topic | Reason |
|-------|--------|
| [Billing disputes] | Financial, requires human judgment |
| [Data deletion] | Compliance, irreversible |
| [Access control] | Trust/security sensitive |

## Recommendations
1. **[Recommendation]** — Evidence: [source]
2. ...

## Sources Used
- [file paths]

## Claims Ledger
| Claim | Type | Source |
|-------|------|--------|
| [High volume in X] | Evidence | [article count] |
| [Users struggle with Y] | Evidence | [VOC file] |

Step 6: Copy to History & Update Tracker

• Copy to history/analyzing-kb-gaps/kb-gaps-YYYY-MM-DD.md
• Update alerts/stale-outputs.md

Quick Reference

Risk Level	Examples	Action
Low	Search improvements, FAQ bots	Safe to build
Medium	Troubleshooting assistants	Build with guardrails
High	Billing, compliance, security	Human only

Common Mistakes

• Counting wrong: "Many articles" → Exact count: "47 articles"
• Missing VOC correlation: KB analysis in isolation → Cross-reference with VOC
• Underestimating risk: "AI can handle billing" → Compliance topics need humans
• No priorities: "Everything is a gap" → Rank by impact
• Stale analysis: Using old VOC → Check VOC synthesis date

Verification Checklist

• All KB files read
• Article counts accurate
• Outdated articles identified (6+ months)
• VOC correlation checked (if available)
• AI opportunities categorized by risk
• DO NOT automate list includes compliance/billing/trust topics
• Recommendations backed by evidence
• Metadata header complete
• Copied to history, tracker updated

Evidence Tracking

Claim	Type	Source
[47 articles on X]	Evidence	[KB export count]
[Users complain about Y]	Evidence	[VOC file:line]
[Safe to automate Z]	Assumption	[no compliance concern identified]