vm-ticket-cluster-analyzer

Skill detail with category, linked agents, and source metadata.

vm-ticket-cluster-analyzer

Groups a normalized set of incident tickets into clusters by symptom type, affected application area, and recurring error pattern using dynamic rule discovery from the data. Supports pre-deduplicated input and 3-layer hybrid assignment (area-exact, fuzzy substring, TF-IDF cosine). Produces a cluster array with member ticket IDs, per-cluster statistics, and keyword signatures. USE FOR: structuring raw ticket data before EASE classification or L-3 candidacy scoring. DO NOT USE FOR: classifying clusters against the EASE framework (use vm-ease-classifier), root cause analysis, or reading ticket data from live APIs.

Category: incident-analytics Used by 1 agents

Source: .github/skills/incident-analytics/vm-ticket-cluster-analyzer/SKILL.md

Used By Agents

3 - Analysis - Incident EASE Analysis Agent

Preview

View source preview (first 3000 chars)


# vm-ticket-cluster-analyzer

## When To Use This Skill

- A normalized ticket array has been prepared and needs to be grouped before EASE classification
- An incident analytics workflow needs ticket clusters with member IDs and frequency statistics
- Bulk ticket data needs to be partitioned into manageable, named issue groups before deeper analysis

**Do NOT use this skill when:**
- The input is a single ticket (clustering requires more than one ticket)
- Tickets have not been normalized into the standard internal structure (the invoking agent must normalize first)
- Classification against the EASE framework is the goal (that is `vm-ease-classifier`)
- Tickets need to be fetched from a live API (that is outside this skill's scope)

## Unitary Function

**ONE RESPONSIBILITY:** Group a normalized ticket array into named clusters by symptom type, affected area, and error pattern; return each cluster with its member ticket IDs and frequency statistics.

**NOT RESPONSIBLE FOR:**
- Normalizing raw CSV or JSON ticket data (agent Phase 1 responsibility)
- EASE classification of clusters (that is `vm-ease-classifier`)
- Temporal pattern analysis (agent Phase 4 responsibility)
- L-3 candidacy scoring (agent Phase 5 responsibility)
- Reading ticket data from any file or API

## Input

```json
{
  "tickets": [
    {
      "ticket_id": "INC-001",
      "summary": "Payment fails at checkout for Visa cards",
      "description": "Users report error code 402 when submitting payment",
      "area": "checkout",
      "priority": "high",
      "created_at": "2026-01-15T09:23:00Z",
      "resolved_at": "2026-01-15T14:00:00Z",
      "resolution_notes": "Restarted payment gateway connector",
      "normalized_text": "payment fails checkout visa cards",
      "itsm_category": "Application",
      "itsm_subcategory": "Payment Processing"
    }
  ],
  "application_name": "Customer Portal",
  "pre_deduped": true
}
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `tickets` | array | MUST | Normalized ticket records conforming to the internal structure |
| `application_name` | string | MAY | Application name used to label cluster context in output |
| `pre_deduped` | boolean | MAY | If true, input has been deduplicated; tickets are unique or merge representatives. Default: false |
| `pii_token_patterns` | array | MAY | List of lowercased tokens from PII reverse lookup (from vm-pii-anonymizer) to filter from TF-IDF vocabulary and cluster names |
| `schema_column_names` | array | MAY | List of normalized column names from the source data schema, used to filter TF-IDF vocabulary and prevent source field names from becoming cluster keywords |

## Output

```json
{
  "generated_by": {
    "skill": "vm-ticket-cluster-analyzer",
    "version": "2.0.0"
  },
  "total_tickets": 142,
  "total_clusters": 8,
  "clusters": [
    {
      "cluster_id": "CLU-001",
      "cluster_name": "Payment Gateway Failure - Checkout",
      "symptom_type": "payment-failure",