--- name: internal-knowledge-base-agents description: Create, maintain, and utilize an internal knowledge base exclusively for support agents containing troubleshooting guides, workarounds, insider tips, scripts, and escalation procedures. Use when building agent-only KB, creating internal troubleshooting guides, documenting known bugs and workarounds, writing escalation procedures, developing agent quick reference guides, or managing internal documentation. Triggers on phrases like "internal knowledge base", "agent KB", "internal documentation", "agent troubleshooting guide", "known bugs", "internal wiki", "agent reference", "insider knowledge". --- # Internal Knowledge Base for Agents Build and maintain a comprehensive, agent-exclusive knowledge repository containing technical troubleshooting guides, known issues, internal workarounds, and insider knowledge not suitable for customer-facing documentation. ## Workflow ### 1. Content Strategy and Organization 1. **Content taxonomy and structure**: ``` INTERNAL KB ORGANIZATION ========================= 1. PRODUCT TROUBLESHOOTING ├── Feature-specific troubleshooting (by product module) │ ├── Authentication & SSO │ ├── API & Integrations │ ├── Billing & Payments │ ├── Data Import/Export │ ├── Reporting & Analytics │ └── [Each major feature area] ├── Error code reference (complete list with root causes) ├── Browser/device compatibility matrix └── Performance troubleshooting (slow loading, timeouts) 2. KNOWN ISSUES & WORKAROUNDS ├── Active known issues (open engineering tickets) ├── Temporary workarounds (by issue) ├── Expected fix dates and customer communication templates └── Resolved issues archive (for reference) 3. CUSTOMER ACCOUNT PROCEDURES ├── Account operations (create, modify, delete, merge) ├── Billing operations (refunds, credits, plan changes) ├── Data operations (export, migration, deletion) ├── Access management (role changes, user additions) └── Compliance requests (GDPR, data access, deletion) 4. ESCALATION PROCEDURES ├── Technical escalation (L2/L3/E engineering) ├── Billing escalation (finance team) ├── Legal/compliance escalation ├── Security incident escalation └── Executive escalation protocols 5. AGENT TOOLS & RESOURCES ├── Admin panel guides (internal tools) ├── Database query references ├── Log analysis procedures ├── Testing and reproduction steps └── Diagnostic tool usage 6. SCRIPTS & TEMPLATES ├── Customer communication templates (internal-only versions) ├── Escalation request templates ├── Bug report templates for engineering ├── Internal collaboration templates └── Status update templates 7. ONBOARDING & TRAINING ├── New agent onboarding checklist ├── Product deep-dive guides ├── Common scenarios with solutions ├── Agent certification materials └── FAQ from new agents (and answers) ``` 2. **Content ownership and governance**: - **Subject matter experts (SMEs)**: Product engineers, billing specialists, security team — own accuracy of their domain - **Content managers**: Dedicated staff who maintain article quality, formatting, and organization - **Agent contributors**: All agents can suggest edits, add troubleshooting tips, flag outdated content - **Review cycle**: Monthly for active issues, quarterly for procedures, annually for training content - **Version control**: Track article versions, authors, last review date, and change history 3. **Content creation workflow**: - **Trigger**: New issue discovered, process change, product update, agent knowledge gap identified - **Draft**: SME or experienced agent creates initial content - **Review**: Peer review by another SME or content manager - **Approval**: Domain owner approves (especially for workarounds and escalation procedures) - **Publish**: Goes live in internal KB with proper tagging - **Maintenance**: Scheduled reviews and updates on cadence ### 2. Advanced Content Types 1. **Troubleshooting decision trees**: - Visual flowcharts for complex issue diagnosis - "If error X → check Y → if Z → do A, else do B" - Include: symptoms, likely causes, diagnostic steps, resolution paths - Link to relevant log analysis procedures and reproduction steps - Example: "API returning 500 errors" decision tree with 12 decision points 2. **Known bugs database**: - Each bug entry includes: - Bug ID (linked to engineering ticket) - Description and reproduction steps - Affected product versions and customer segments - Impact severity (P1-P4) - Current workaround (if available) - Expected fix timeline and status - Customer communication template (what to tell customers) - Related internal KB articles - Auto-link to engineering ticket status updates - Flag bugs approaching customer-facing threshold (3+ tickets) 3. **Internal scripts and tools documentation**: - Database queries for common account operations - API calls for internal admin functions - Log search queries for debugging - Automation scripts and their usage - Sandbox/testing environment access and procedures - Each script includes: purpose, prerequisites, usage instructions, output interpretation, warnings 4. **Customer account deep-dive templates**: - How to investigate account-specific issues - Database queries for account data (with security notes) - How to check API key status, webhook configurations, billing state - How to reproduce customer's exact environment in staging - Escalation data to include when escalating to engineering ### 3. Search, Discovery, and Usage 1. **Internal search capabilities**: - Full-text search across all internal KB content - Advanced filters: Content type, product area, last updated, author - Error code lookup: Type any error code → get root cause, workaround, customer script - Fuzzy matching: Handles typos, partial terms, alternative phrasings - Search analytics: Track most-searched terms to identify content gaps - Recent/popular articles sidebar 2. **Agent integration with help desk**: - Internal KB sidebar in help desk workspace - Auto-suggest articles when agent opens ticket (based on ticket content) - One-click insert of internal notes, customer scripts, or troubleshooting steps - Quick-search bar in compose area - "Was this article helpful?" feedback loop 3. **Usage analytics and gap identification**: - Track: Article views, search terms with no results, time spent per article, helpfulness ratings - Identify content gaps: Frequently searched terms with no matching articles - Identify outdated content: Articles with high views but low helpfulness - Generate weekly content gap report for content managers - Track agent adoption: % of agents using internal KB daily/weekly ### 4. Quality and Maintenance 1. **Content freshness management**: - Auto-flag articles not reviewed in 90 days - Product update integration: When new version released, flag all version-specific articles - Known bugs auto-update: When engineering ticket status changes, update internal KB - Agent feedback: "This article is outdated" button on every article - Monthly content freshness report 2. **Quality standards and review**: - **Quality checklist** for every article: - Accurate and tested (SME verified) - Step-by-step with screenshots where applicable - Clear prerequisites and warnings - Links to related articles - Customer communication language included (what to tell customer) - Version information current - **Peer review process**: All new articles reviewed by another SME before publishing - **Quarterly audit**: Content manager audits 20% of articles per quarter for quality 3. **Security and access control**: - Role-based access: L1 agents (limited), L2 agents (full), Managers (full + edit) - Sensitive content restricted: Database access, customer PII handling, security procedures - Audit logging: Who accessed what, when, and any edits made - Never include customer PII in articles (use anonymized examples) - Quarterly access review: Verify agent access levels are appropriate ## Templates & Frameworks ### Internal KB Dashboard ``` INTERNAL KB DASHBOARD — December 2025 ======================================== CONTENT OVERVIEW: Total articles: 847 Active this month: 312 (36.8%) New articles this month: 23 Articles updated this month: 67 Articles flagged for review: 42 Articles archived this month: 8 CONTENT BY CATEGORY: Category | Articles | Active/Mo | Avg Views/Mo | Health Score ----------------------------|----------|-----------|--------------|------------ Product Troubleshooting | 287 | 145 | 4,230 | 92/100 ✓ Known Issues & Workarounds | 89 | 52 | 2,890 | 88/100 ✓ Customer Account Procedures | 124 | 38 | 1,560 | 85/100 ✓ Escalation Procedures | 42 | 18 | 890 | 90/100 ✓ Agent Tools & Resources | 156 | 67 | 3,120 | 82/100 ⚠ Scripts & Templates | 98 | 45 | 2,340 | 87/100 ✓ Onboarding & Training | 51 | 15 | 680 | 79/100 ⚠ USAGE METRICS: Daily active users (agents): 36 of 42 (85.7%) Weekly active users: 41 of 42 (97.6%) Average searches per agent/day: 4.7 Average articles viewed per agent/day: 2.3 Average time to find answer: 47 seconds (target: <60 seconds) ✓ Article helpfulness rating: 4.3/5.0 avg SEARCH ANALYTICS: Total searches this month: 5,240 Searches with results: 4,780 (91.2%) Searches with no results: 460 (8.8%) TOP SEARCH TERMS WITH NO RESULTS (content gaps): 1. "webhook retry policy" — 23 searches, no article 2. "custom domain SSL renewal" — 18 searches, no article 3. "SSO SAML debugging" — 15 searches, partial match only 4. "bulk user import error 5003" — 12 searches, no article 5. "API versioning migration" — 10 searches, outdated article only ACTION: Create articles for top 5 gaps — assigned to content team KNOW ISSUES STATUS: Active known issues: 12 Issues with documented workaround: 10 (83.3%) Issues without workaround: 2 ⚠ (escalated to engineering) Issues resolved this month: 7 Average time from bug report to KB article: 4.2 hours CONTENT FRESHNESS: Articles reviewed in last 30 days: 67 (7.9%) Articles reviewed in last 90 days: 234 (27.6%) Articles NOT reviewed in 90+ days: 613 (72.4%) ⚠ Articles flagged as potentially outdated: 38 Next scheduled audit: January 15, 2026 AGENT FEEDBACK: "Helpful" ratings: 3,890 (88% of rated articles) "Needs improvement" ratings: 312 (7%) "Outdated" flags: 89 (2%) Total article suggestions: 34 Articles created from agent suggestions: 18 (53%) ``` ### Internal Troubleshooting Article Template ``` INTERNAL KB ARTICLE TEMPLATE — Troubleshooting ================================================ TITLE: [Clear, searchable title — include error code or symptom] ARTICLE ID: KB-INT-[YYYY]-[####] CATEGORY: [Product Troubleshooting / Known Issue / Procedure / Tool] PRODUCT AREA: [API / Billing / Auth / etc.] PRODUCT VERSIONS: [Affected versions] LAST UPDATED: [YYYY-MM-DD] AUTHOR: [Name] REVIEWER: [Name] NEXT REVIEW: [YYYY-MM-DD] ACCESS LEVEL: [L1+ / L2+ / Manager+] SYMPTOMS: • [What the customer reports — verbatim examples] • [What you see in logs/admin panel] • [Error codes or messages] SEARCH TERMS: [Common ways agents/customers search for this issue] PREREQUISITES: • [Required access levels or tools] • [Information needed before starting troubleshooting] • [Environments where this applies] ROOT CAUSE: [Brief explanation of why this happens — for agent understanding] TROUBLESHOOTING STEPS: Step 1: [Action] • [Specific instruction] • Expected result: [What you should see] • If different: [Go to step X or note below] Step 2: [Action] • [Specific instruction] • [Include screenshots if helpful] • Expected result: [What you should see] Step 3: [Action] • ... [Continue with numbered steps...] RESOLUTION: [What to do once root cause is identified] [Customer action vs agent action — clearly labeled] WORKAROUND (if permanent fix pending): [Temporary solution to provide to customer] [Known limitations of workaround] [Expected fix timeline: [Date/Version]] CUSTOMER COMMUNICATION: What to tell customer: "We've identified the issue. This is caused by [customer-friendly explanation]. Here's what we're doing: [action]. You can [workaround] in the meantime. We expect this to be fully resolved by [timeline]." DO NOT SAY: [Internal information that shouldn't reach customer] RELATED ARTICLES: • [Link to related KB articles] • [Link to known issue if applicable] ESCALATION: When to escalate: [Specific conditions] Escalation path: [Team/individual] Information to include: [Checklist of data to gather before escalating] LOGS AND DIAGNOSTICS: [Relevant log paths or queries] [What to look for in logs] [How to interpret results] CHANGE HISTORY: [YYYY-MM-DD]: [Author] — [Change description] [YYYY-MM-DD]: [Author] — [Change description] ``` ### Known Issues Tracking Template ``` KNOWN ISSUE TRACKER ==================== Issue ID: KN-2025-042 Engineering Ticket: ENG-8934 Status: 🔴 Active — Workaround Available Severity: P2 (Affecting multiple customers, workable) Discovered: 2025-11-28 Expected Fix: 2025-12-15 (v3.2.1 patch) DESCRIPTION: Webhook delivery to endpoints using self-signed SSL certificates fails with "SSL handshake error" instead of being retried. Affected only on API v3. API v2 unaffected. AFFECTED CUSTOMERS: Estimated: 23 accounts (8.4% of webhook-using accounts) Confirmed reports: 14 tickets this week Customer segments: Enterprise (6), Mid-market (5), SMB (3) Industries: Healthcare (4), E-commerce (5), SaaS (5) REPRODUCTION STEPS: 1. Customer sets up webhook endpoint with self-signed SSL certificate 2. System attempts delivery via API v3 3. SSL handshake fails, delivery marked as "failed" (not retried) 4. Customer receives no retry or error notification WORKAROUND: 1. Option A: Customer uses trusted SSL certificate (Let's Encrypt, commercial CA) - Customer script: "We recommend using a trusted SSL certificate for webhook endpoints. Here's a guide to setting up free SSL with Let's Encrypt: [link]" 2. Option B: Downgrade webhook to API v2 (temporary, v2 unaffected) - Agent action: Use admin panel → Webhooks → Change version → v2 - Note: v2 deprecation planned for Q2 2026 CUSTOMER COMMUNICATION: Acknowledged: "We're aware of an issue with webhook SSL handling in our latest API version. Our engineering team is working on a fix. In the meantime, you can [workaround]. We'll notify you when this is resolved." Proactive outreach: All 23 affected accounts contacted on 2025-11-29 RESOLUTION UPDATE TIMELINE: 2025-11-28: Issue identified and reported to engineering 2025-11-29: Root cause confirmed (SSL library change in v3) 2025-11-29: Workaround documented, affected customers notified 2025-12-05: Engineering fix in progress (code review) 2025-12-10: Fix deployed to staging, QA testing 2025-12-15: Expected production release (v3.2.1) 2025-12-16: Post-fix customer notification planned METRICS: Tickets created: 14 (target: <5 with proactive outreach) Customer complaints: 3 (all resolved with workaround) Churn risk: Low (workaround effective for 13/14 reported customers) Engineering priority: P2 → Escalating to P1 if ticket volume increases ESCALATION THRESHOLDS: >20 tickets: Escalate to VP Engineering Any churn threat: Immediate executive escalation Security concern: Security team notification ``` ## Integration Points - **Help desk systems** (Zendesk, Freshdesk, Intercom): Sidebar integration; auto-suggest; search from ticket view; article feedback - **Internal documentation platforms** (Confluence, Notion, Guru): Primary content management; version control; access control - **Engineering ticketing** (Jira, Linear): Known issues sync; bug status updates; fix timeline tracking - **Communication platforms** (Slack, Teams): New article notifications; content update alerts; agent collaboration - **Product analytics**: Feature adoption data for context; error tracking for troubleshooting content - **Admin tools and dashboards**: Internal admin panel documentation; database query references - **LMS** (Lessonly, Docebo): Training content sync; certification materials - **Search engines** (Elasticsearch, Algolia): Full-text search; search analytics; recommendation engine ## Edge Cases - **Sensitive workaround information**: Workaround requires database manipulation or admin panel access not available to L1 agents: - Access level restrictions on articles (L2+ only) - Clear instructions on what NOT to do (preventing accidental data corruption) - Require manager approval before executing sensitive workarounds - Audit logging of all workaround executions - Monthly review of sensitive article access patterns - **Content becomes outdated after product release**: Product update changes behavior documented in 50+ articles: - Version-tag all articles with applicable product versions - Post-release: Content manager reviews all articles tagged for affected version - Auto-flag articles not updated within 5 business days of release - "Verified for v3.2" badge on reviewed articles - Agent notification: "5 articles have been updated for v3.2" - **Agents contributing conflicting information**: Two agents edit same article with contradictory troubleshooting steps: - Edit approval workflow: L1 suggestions reviewed by L2+, L2 edits reviewed by SME - Change notification: Original author and reviewers notified of edits - Dispute resolution: Content manager mediates conflicting edits - Version history: Full change history visible, ability to revert - **KB usage varies significantly by agent**: Some agents use internal KB heavily, others rarely: - Track individual agent usage patterns monthly - Low-usage agents: 1:1 coaching on KB benefits; assign "KB champion" mentor - High-usage agents: Invite to contribute content; recognize as SME - Team goals: 80%+ weekly active users; 4+ searches/agent/day - New hire onboarding: KB tour during first week - **Internal KB knowledge loss from agent turnover**: Experienced agent leaves, taking tribal knowledge: - Exit interview includes: "What do you know that isn't documented?" - Mandatory documentation of unique troubleshooting approaches before departure - "Agent expertise mapping": Track which agents are go-to for which topics - If single point of knowledge identified: Assign documentation task to broaden coverage - Quarterly review: Identify topics with only 1 expert ## Output ### Internal KB Monthly Report ``` INTERNAL KB MONTHLY REPORT — December 2025 ============================================= CONTENT HEALTH: Total articles: 847 (↑ 15 from November) Articles reviewed this month: 89 (10.5%) Articles updated for v3.2 release: 34 Articles archived: 8 (deprecated features) Content freshness score: 74/100 ⚠ (target: >80) CONTENT GAPS ADDRESSED: ✅ "Webhook retry policy" — Article created (23 pending searches) ✅ "Custom domain SSL renewal" — Article created (18 pending searches) ✅ "Bulk user import error 5003" — Article created (12 pending searches) ⏳ "SSO SAML debugging" — Article in review (15 pending searches) ⏳ "API versioning migration" — Old article being rewritten (10 pending searches) USAGE IMPACT: Daily active users: 38/42 agents (90.5%, ↑ 4.8% from November) Average resolution time with KB vs without: 11 min vs 19 min (-42%) First contact resolution improvement with KB usage: +18% New hire ramp time with KB: 4 weeks (vs 7 weeks without) Agent satisfaction with internal KB: 4.2/5.0 KNOW ISSUES MANAGEMENT: Active known issues: 12 (↓ 3 from November) Issues with documented workaround: 10 (83%) Customer-facing articles for known issues: 12 (100% coverage) Average time from discovery to documentation: 4.2 hours Proactive customer outreach completed: 23 accounts (100% of affected) QUALITY METRICS: Article helpfulness rating: 4.3/5.0 (↑ 0.1 from November) Agent feedback submissions: 34 (18 implemented) "Outdated" flags resolved: 28 of 38 (74%) Peer review completion: 100% of new articles reviewed before publishing RECOMMENDATIONS: 1. Content freshness priority: 613 articles need review (72% of library) 2. Assign content owners for Agent Tools category (health score 82 — lowest) 3. Create "SSO SAML debugging" and "API versioning migration" articles (pending) 4. Launch KB contribution incentive program (increase agent-submitted content) 5. Implement automated version-tagging for release cycle content updates ```