process_helpscout/config_files/topics.json

{
  "_meta": {
    "version": "1.0.0",
    "last_updated": "2025-04-09",
    "description": "Musora HelpScout auto-tagging taxonomy. Used as the source configuration for the LLM-based tagging pipeline. Topics are mutually exclusive at the top level; a conversation may receive multiple topic tags. Sub-categories are listed for reference and future use in a separate config. Special boolean flags are defined inline for high-signal billing events.",
    "usage_notes": [
      "Assign one or more topic tags per conversation.",
      "Boolean flags under billing_and_subscription should be extracted independently even when the parent topic is detected.",
      "Use the 'uncategorized' topic when no other topic clearly applies — never as a fallback for uncertain cases.",
      "feedback_and_suggestions should be used as a supplementary tag alongside a primary topic when applicable."
    ]
  },

  "topics": [

    {
      "id": "video_and_playback",
      "label": "Video & Playback",
      "description": "The student is experiencing a problem with audio or video content during viewing. The issue is with how media plays, not with the surrounding app or UI. "
    },

    {
      "id": "app_and_technical_errors",
      "label": "App & Technical Errors",
      "description": "A software bug, crash, or system failure that is NOT limited to video playback. The app, website, technology related, or a specific feature is broken, unresponsive, or showing an error message. Use this when the problem is with the platform itself rather than the content being watched."
    },

    {
      "id": "navigation_and_ux",
      "label": "Navigation & UX",
      "description": "The student is confused by the interface or cannot find something, but is not technically blocked from accessing it. The issue is about discoverability, layout clarity, or unintuitive design rather than a bug or access restriction. Often triggered by redesigns or renamed features."
    },
    {
      "id": "account_and_access",
      "label": "Account & Access",
      "description": "The student cannot log in, is locked out, or cannot access content they are entitled to. Also covers profile and settings issues. Distinct from billing: use this when the problem is authentication or permissions, even if the underlying cause might be a billing state."
    },

    {
      "id": "billing_and_subscription",
      "label": "Billing & Subscription",
      "description": "Any conversation involving money, charges, plan status, or membership. This includes unexpected charges, plan changes, promotions, and invoice requests. ",
      "flags": {
        "is_refund_request": {
          "type": "boolean",
          "description": "True when the student is explicitly asking for their money back, regardless of reason."
        },
        "is_cancellation": {
          "type": "boolean",
          "description": "True when the student wants to cancel their subscription or membership, even if they haven't asked for a refund."
        },
        "is_membership": {
          "type": "boolean",
          "description": "True when the student wants to join/rejoin and purchase membership."
        }
      }
    },

    {
      "id": "learning_and_progress",
      "label": "Learning & Progress",
      "description": "Issues with how the student's learning journey, including asking for help or recommendations, is tracked or structured over time. Covers broken progress tracking, practice session logging, playlist management, curriculum navigation, and access to legacy or assigned content. The problem is with the learning system, not the content itself."
    },

    {
      "id": "content_and_resources",
      "label": "Content & Resources",
      "description": "Problems with the lesson content itself or supplementary learning materials — not the video player. Covers missing PDFs, sheet music, backing tracks, incorrect lesson information, requests for new content, and missing assignment or review links."
    },

    {
      "id": "community_and_notifications",
      "label": "Community & Notifications",
      "description": "Issues involving forums, comments, student profiles, social features, or the delivery of notifications. Use this when the problem is about communication and social interaction within the platform, not content access or playback."
    },

    {
      "id": "feedback_and_suggestions",
      "label": "Feedback & Suggestions",
      "description": "The student is sharing an opinion, making a feature request, or expressing general satisfaction or dissatisfaction — not reporting a specific failure. This should typically be applied as a supplementary tag alongside a primary topic when a complaint conversation also carries strong sentiment or a request for new functionality."
    },

    {
      "id": "uncategorized",
      "label": "Uncategorized",
      "description": "Assign ONLY when no other topic clearly applies after careful consideration. Do not use as a fallback for low-confidence cases where a topic still partially fits — prefer the closest matching topic. The primary purpose of this tag is to surface new conversation patterns that may warrant expanding the taxonomy."
    }

  ]
}