--- name: smart-faq-builder description: Automatically generate, maintain, and optimize FAQ pages based on actual customer support ticket patterns, search queries, and common questions. Use when creating FAQ content, identifying FAQ gaps, auto-generating FAQs from tickets, optimizing FAQ performance, managing FAQ lifecycle, or reducing support volume through self-service. Triggers on phrases like "FAQ builder", "auto-generate FAQ", "FAQ content", "frequently asked questions", "FAQ optimization", "FAQ from tickets", "self-service FAQ", "FAQ management". --- # Smart FAQ Builder & Management Automatically extract, create, and maintain FAQ content from real customer support interactions to maximize self-service deflection. ## Workflow ### 1. FAQ Mining from Support Tickets 1. **Continuous ticket analysis**: - Ingest all resolved support tickets daily from help desk system - Parse customer questions (first message) and agent answers - Extract question patterns: "How do I...?", "Why does...?", "Can I...?" - Group semantically similar questions using NLP clustering - Score each question group by frequency (tickets in last 30/60/90 days) 2. **Question clustering and deduplication**: - "How do I reset my password?" clusters with "Can I change my password?" and "Password reset steps" - NLP similarity threshold: >85% match = same question - Track variant count per cluster (how many ways customers ask the same thing) - Identify the clearest, most searched phrasing as canonical FAQ title 3. **Answer extraction and formatting**: - Pull agent response that received highest CSAT (>4.5 stars) - Clean response: remove customer-specific details, personalize templates - Extract step-by-step instructions - Flag any screenshots, links, or code snippets needed - Format as structured content: problem statement → prerequisites → solution steps → related articles ### 2. FAQ Generation and Publishing 1. **Draft FAQ creation**: - Auto-generate FAQ entry with: title, question variants, answer body, category, tags - Assign quality score based on: completeness (1-5), clarity (1-5), evidence quality (1-5) - Score ≥12: auto-approve for draft queue - Score 8-11: flag for review by content specialist - Score <8: request source agent to improve answer before extraction 2. **Review and approval workflow**: - Content specialist reviews draft FAQ in approval queue - Checks: accuracy, completeness, brand voice, formatting, links - Edits if needed, then publishes to help center - Rejected FAQs logged with reason for process improvement - Average review SLA: 24 hours for high-priority (30+ tickets/month), 72 hours for standard 3. **Publication and promotion**: - Published FAQs go live on help center with proper URL slug and SEO meta - Auto-promoted to relevant KB article sidebars - Added to chatbot response library for bot deflection - Linked from related product pages (via CMS integration) - Indexed for search with proper taxonomy ### 3. FAQ Optimization and Performance 1. **Performance tracking**: - Track per FAQ: views, unique visitors, bounce rate, time on page, helpfulness votes - Calculate deflection rate: views → no ticket created within 24 hours - Monitor search terms leading to each FAQ - Track FAQ-to-ticket creation ratio (low ratio = effective deflection) 2. **Content optimization triggers**: - FAQ with >200 views but <30% helpfulness: flag for rewrite - FAQ with increasing ticket creation after views: content likely outdated or incomplete - FAQ with declining views over 90 days: may need retitling or SEO improvement - FAQ with high bounce rate (>80%): content doesn't match user intent 3. **A/B testing and improvement**: - Test FAQ title variations for click-through improvement - Test content formats: step-by-step vs narrative, video embed vs screenshots - Measure improvement in helpfulness and deflection - Deploy winning variant as default ### 4. FAQ Lifecycle Management 1. **Obsolescence detection**: - Monitor product changelog for feature changes that affect FAQs - When feature deprecated, auto-flag related FAQs for review - Track FAQ age: articles >6 months old get auto-review reminder - Customer comments flagging "this doesn't work" or "outdated" trigger review - Bounce rate spike indicates content mismatch → auto-review 2. **Sunset and archive**: - FAQs with <5 views/month for 6 consecutive months: archive - Archived FAQs removed from search but retained in archive with redirect - Archive reason logged: superseded, deprecated, merged - Monthly archive report sent to content team 3. **Bulk operations**: - Mass tag update for category restructuring - Bulk publish for seasonal FAQs (holiday support, tax season) - Scheduled publishing (e.g., "How to use new feature X" publishes on launch day) - Bulk archive for deprecated product line FAQs ## Templates & Frameworks ### FAQ Mining Dashboard ``` FAQ MINING DASHBOARD — May 2025 ================================ TICKET ANALYSIS PIPELINE: Total tickets analyzed (last 30 days): 1,847 Unique question clusters identified: 142 Clusters with ≥5 tickets: 38 Clusters with ≥10 tickets: 14 (high priority for FAQ creation) TOP FAQ CANDIDATES BY FREQUENCY: Rank | Question Cluster | Tickets/Mo | Current FAQ | Priority -----|-------------------------------------|------------|-------------|--------- 1 | How to reset password | 47 | ✅ Exists | Update 2 | How to cancel subscription | 34 | ✅ Exists | Monitor 3 | How to add team members | 29 | ❌ Missing | CREATE 4 | API rate limit exceeded error | 26 | ❌ Missing | CREATE 5 | How to integrate with Slack | 23 | ✅ Exists | Update 6 | Billing discrepancy on invoice | 21 | ❌ Missing | CREATE 7 | How to export data | 19 | ✅ Exists | Monitor 8 | SSO setup for enterprise | 17 | ❌ Missing | CREATE 9 | How to change plan tier | 15 | ✅ Exists | Monitor 10 | Webhook configuration guide | 14 | ❌ Missing | CREATE CONTENT CREATION QUEUE: Drafts pending review: 8 Approved but unpublished: 3 Published this month: 12 Archived this month: 4 Total active FAQs: 187 PERFORMANCE METRICS: FAQ pages viewed (last 30 days): 14,230 Estimated ticket deflection: 8,540 Average helpfulness score: 4.3/5.0 Search-to-FAQ conversion rate: 62% FAQ-to-ticket ratio (lower = better): 18% Top performing FAQ: "API Authentication Guide" (2,340 views, 91% deflection) Worst performing FAQ: "Legacy Migration Steps" (890 views, 31% deflection) ⚠ SEO PERFORMANCE: Organic search traffic to FAQs: 3,120/mo New keywords ranking (FAQ pages): 47 Average position for target keywords: 3.2 FAQ pages in Google "People Also Ask": 12 ``` ### FAQ Quality Scorecard ``` FAQ QUALITY SCORECARD ===================== Content Structure (25 points): [ ] Clear, single-question title (5 pts) [ ] Problem statement at top (5 pts) [ ] Numbered steps for procedures (5 pts) [ ] Screenshots with annotations where needed (5 pts) [ ] Related articles / next steps (5 pts) Clarity & Tone (25 points): [ ] Written in plain language (no jargon) (5 pts) [ ] Consistent brand voice (5 pts) [ ] Reads at 8th-grade level or below (5 pts) [ ] Active voice throughout (5 pts) [ ] Scannable format (headers, bullets) (5 pts) Accuracy & Completeness (25 points): [ ] Steps tested and verified (5 pts) [ ] All edge cases addressed (5 pts) [ ] Error messages explained (5 pts) [ ] Prerequisites listed (5 pts) [ ] Troubleshooting section included (5 pts) Discoverability (25 points): [ ] Proper category and tags assigned (5 pts) [ ] SEO-optimized title and meta description (5 pts) [ ] Linked from related articles (5 pts) [ ] Searchable question variants included (5 pts) [ ] URL slug is clean and keyword-rich (5 pts) Minimum passing score: 70/100 Target score: 90+/100 Review cycle: Monthly for low-scoring, Quarterly for high-scoring ``` ## Data Models and Metrics ### FAQ Deflection Impact Model ``` DEFLECTION IMPACT CALCULATION ============================== Per FAQ: Monthly views: 500 Helpfulness rate: 78% Post-view ticket creation rate: 15% (vs 45% average for non-FAQ paths) Estimated deflection: 500 × 78% × (45% - 15%) = 117 tickets/month prevented Cost Savings Model: Average cost per ticket: $14.50 Tickets prevented by FAQs (monthly): 2,340 Monthly savings: 2,340 × $14.50 = $33,930 Annual savings: $407,160 FAQ ROI by Category: Category | FAQs | Monthly Deflection | Monthly Savings -------------------|------|--------------------|--------------- Account Setup | 12 | 420 | $6,090 Billing & Payment | 8 | 310 | $4,495 API Integration | 15 | 580 | $8,410 Troubleshooting | 22 | 670 | $9,715 Feature How-To | 31 | 360 | $5,220 Total FAQ library deflection: 2,340 tickets/month Total monthly savings: $33,930 Annual savings: $407,160 Content investment (content team FTE): $62,400/year Net annual ROI: $344,760 (5.5x ROI) ``` ### FAQ Lifecycle Timeline ``` FAQ LIFECYCLE MANAGEMENT ========================= Day 0: Question identified in ticket clustering (≥5 occurrences in 30 days) Day 1: Draft FAQ auto-generated from best agent response Day 2: Content specialist review (24-hour SLA) Day 3: Published to help center, added to search index, promoted to chatbot Day 7: First performance check (views, helpfulness, deflection rate) Day 30: Monthly performance review — optimize if below targets Day 60: Content freshness check — compare to product state Day 90: Quarterly full review — rewrite if helpfulness < 4.0 Day 180: Six-month health check — archive if <5 views/month for 60 days Day 365: Annual archive review — purge or renew archived FAQs Automated Triggers: - Product update published → Flag all FAQs referencing changed features - Customer comments "outdated" on FAQ → Auto-assign review task - Helpfulness drops below 3.5/5.0 for 14 consecutive days → Rewrite alert - Views spike >200% → Verify content is current (could indicate new issue) - Related article updated → Cross-check FAQ for consistency ``` ## Integration Points - **Help desk systems** (Zendesk, Freshdesk, Intercom): Source ticket data for FAQ mining; push published FAQs as suggested articles in ticket creation flow - **Knowledge base platforms** (Zendesk Guide, Confluence, Notion): Publish and manage FAQ content; version control; approval workflows - **Search engines** (Elasticsearch, Algolia): Index FAQs for semantic search; track search-to-FAQ conversion - **Chatbot platforms** (Intercom, Drift, custom): Feed FAQ answers to chatbot response library for automated deflection - **Content management systems** (WordPress, Sanity, Contentful): Push FAQs to product pages and landing pages - **Analytics platforms** (Google Analytics, Mixpanel): Track FAQ page performance, user behavior, and conversion metrics - **SEO tools** (Ahrefs, SEMrush): Monitor FAQ page rankings; identify keyword opportunities - **AI/NLP services** (OpenAI, Anthropic): Question clustering, answer extraction, quality scoring, obsolescence detection ## Edge Cases - **Contradictory answers across tickets**: When same question has multiple valid answers (e.g., for different product versions or plan tiers), create FAQ with branching logic: "If you're on [Plan A], do X; if on [Plan B], do Y" - Implement tabbed content or accordion sections for each scenario - Test each path independently for accuracy - Add prominent indicator for user to select their scenario - **Highly technical questions**: API-level or code-specific questions need special formatting: - Include code samples with syntax highlighting - Link to developer documentation - Add version-specific notes (API v2 vs v3) - Provide curl examples alongside SDK code - **Multi-language FAQ needs**: When support tickets come in multiple languages: - Create FAQ in source language, then translate using professional translation (not just machine translation) - Maintain separate content review per language - Track deflection metrics per language - Assign language-specific content owners - **FAQ cannibalizing premium support**: If FAQ on billing resolution is causing enterprise customers to self-resolve rather than engage CSM: - Implement tiered FAQ visibility (some content only for certain plan levels) - Add "Contact your CSM" prompt for enterprise-tier customers - Balance self-service efficiency with relationship-building opportunities - **Regulatory/legally sensitive FAQs**: Content around data privacy, terms of service, or refund policies: - Require legal review before publishing (add to approval workflow) - Date-stamp all regulatory content with "Last reviewed: [date]" - Set 90-day automatic review cycle for compliance content - Restrict editing to authorized content managers only ## Output ### FAQ Creation Report ``` NEW FAQ CREATION REPORT — May 2025 ==================================== FAQS CREATED THIS MONTH: 12 1. "How to Add Team Members to Your Account" Source: 29 tickets in April, avg CSAT on agent response: 4.6/5.0 Category: Account Setup | Tags: team, members, invite, collaboration Expected monthly deflection: 18 tickets ($261/mo savings) Status: ✅ Published May 5 2. "Fixing API Rate Limit Exceeded Errors" Source: 26 tickets in April, primary audience: developers Category: API Integration | Tags: API, rate-limit, error, 429 Includes: Code samples, retry logic examples, rate limit tiers Expected monthly deflection: 16 tickets ($232/mo savings) Status: ✅ Published May 8 3. "Resolving Billing Discrepancies on Your Invoice" Source: 21 tickets, high customer frustration (avg pre-resolution CSAT: 2.1/5.0) Category: Billing & Payment | Tags: billing, invoice, discrepancy, charge Includes: Step-by-step troubleshooting, common causes table, support escalation path Expected monthly deflection: 13 tickets ($188/mo savings) Status: ✅ Published May 12 TOTAL ESTIMATED MONTHLY IMPACT: Tickets deflected: 1,020 additional Cost savings: $14,790 additional/month Cumulative FAQ library savings: $48,720/month REMAINING CONTENT GAPS (Top 10 unresolved clusters): 1. SSO configuration for enterprise (17 tickets/mo) 2. Webhook event setup (14 tickets/mo) 3. Data retention policy questions (12 tickets/mo) 4. Custom domain SSL configuration (11 tickets/mo) 5. Permission role differences (10 tickets/mo) ```