> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Categories

> Use AI-powered categories to automatically classify tickets by topic with name, description, and example phrases that train the classifier.

Categories use AI-powered classification to automatically organize tickets when they're created, analyzing ticket content to determine the best classification match.

## Mental model

A category is a single-label classification assigned to a ticket. Every ticket can have zero or one category. Categories are workspace-scoped and AI-assigned at ticket creation time.

Categories vs. tags:

|                | Categories                                                       | Tags                                    |
| -------------- | ---------------------------------------------------------------- | --------------------------------------- |
| **Per ticket** | Zero or one                                                      | Zero or many                            |
| **Assignment** | Automatic (AI at creation)                                       | Manual, AI-assisted, or workflow-based  |
| **Purpose**    | Primary topic classification                                     | Flexible supplementary labeling         |
| **Mutability** | Can be changed manually or by workflow, but AI will not reassign | Can be added/removed freely at any time |

Use categories for the primary "what is this request about" classification. Use tags for supplementary metadata like urgency, team ownership, or process state.

***

## Classification behavior

Auto-classification runs once: when a ticket is created and has no category already set. The system analyzes the ticket's title, description, and initial messages against all category descriptions and example phrases in the workspace.

**What prevents auto-classification:**

* A category was manually set during ticket creation.
* A workflow assigned a category before the classifier ran.
* The classifier found no confident match (ticket remains unclassified, not assigned to default).

**What does not trigger reclassification:**

* Editing a ticket's title or description after creation.
* Updating category descriptions or examples (affects future tickets only).
* Adding messages to an existing ticket.

Manual category changes always take precedence. The AI will never overwrite a manually assigned category.

***

## Writing effective categories

Classification accuracy depends on the quality of descriptions and example phrases.

**Descriptions** should define the scope clearly and specifically. "Requests to reset user passwords or unlock accounts" is better than "Password stuff."

**Example phrases** should mirror how users actually describe their issues, not how support agents would categorize them:

* Good: "I can't log into my email", "My account is locked out", "Need to reset my credentials"
* Bad: "password", "authentication failure", "credential management"

Include 5-10 diverse examples per category. Cover different phrasings of the same intent.

**Avoiding overlap:** If two categories could reasonably match the same ticket, they overlap. "Password Issues" and "Login Problems" overlap significantly. Combine them into one category or make the descriptions mutually exclusive (e.g., "Password resets for self-service accounts" vs. "SSO and authentication errors with corporate login").

Start with 5-10 core categories. Review tickets landing in the default category to identify patterns that need their own category. Refine examples based on misclassifications.

***

## Integration with agent rules and workflows

**Agent rules:** Reference categories in rules using `@Category Name`. When a category is mentioned in a rule, the agent gains access to that category's details as context.

Common rule patterns:

* Priority escalation: "When a ticket is categorized as @Security Issue, set priority to urgent and assign to the security team."
* Workflow triggers: "If category is @Software Request, trigger @Software Approval Workflow."
* Conditional responses: "For @Password Reset tickets, guide the user through self-service reset before escalating."

**Workflows:** The "Category Assigned" trigger fires when a category is assigned to a ticket (either by AI or manually). Use this to build automation based on ticket topic, such as routing to specialized teams, setting priority, or notifying specific channels.

***

## Constraints and gotchas

* One category per ticket. For multiple labels, use tags.
* Every workspace requires exactly one default category. The default category cannot be deleted.
* Auto-classification only runs at ticket creation. There is no bulk reclassification. Updating category descriptions or examples does not affect existing tickets.
* If the classifier has no confident match, the ticket remains unclassified (no category), not assigned to the default category. The default is only assigned manually.
* Deleting a category removes it from all tickets that had it. Those tickets show "No category" until manually updated.
* Categories are workspace-scoped. There is no way to import categories from one workspace to another directly. Use templates for common starting sets.
* Categories do not sync to external integrations. A category assigned in Ravenna does not appear in Jira, Linear, or other connected systems.
* Template import supports up to 100 categories at once.