vm-pii-anonymizer

# vm-pii-anonymizer

## When To Use This Skill

- Tabular data (DataFrame, CSV, Excel) contains columns that may hold person names, emails, phone numbers, or other PII
- The column schema is unknown or varies across data sources (the LLM must reason about which columns contain PII)
- PII must be masked before any downstream analysis or report generation

**Do NOT use this skill when:**
- The PII columns are already known and hardcoded (use scripts/anonymize-pii.py directly)
- The goal is to anonymize free-text content inside description or summary fields
- The data does not contain any person-attributable fields
- Compliance certification or formal PII audit is required (this is an analytical aid, not a compliance tool)

## Unitary Function

**ONE RESPONSIBILITY:** Detect PII columns in tabular data via LLM reasoning about column names and sample values, then mask detected columns with deterministic anonymous IDs using scripts/anonymize-pii.py.

**NOT RESPONSIBLE FOR:**
- Free-text anonymization (summaries, descriptions, resolution notes)
- Data quality assessment or classification beyond PII detection
- Compliance certification or audit trail generation
- Reading source files (the invoking agent provides column metadata)

## Input

```json
{
  "columns": [
    {
      "name": "Raised By",
      "dtype": "object",
      "sample_values": ["Jane Smith", "John Doe", "Alex Chen"],
      "null_rate": 0.02
    }
  ],
  "application_prefix": "ISU",
  "data_file_path": "/path/to/normalized_data.csv"
}
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `columns` | array | MUST | Column metadata: name, dtype, 3 sample values, null rate |
| `application_prefix` | string | MUST | Prefix for anonymous IDs (e.g., "ISU" produces ISU-P-001) |
| `data_file_path` | string | MUST | Path to the CSV or pickled DataFrame to anonymize |

## Output

```json
{
  "generated_by": {
    "skill": "vm-pii-anonymizer",
    "version": "1.0.0"
  },
  "detected_pii_columns": ["Raised By", "Assignee", "Resolved By"],
  "detection_rationale": {
    "Raised By": "Column name indicates person attribution; sample values are full person names",
    "Assignee": "Column name indicates person assignment; sample values are full person names",
    "Resolved By": "Column name indicates person attribution; sample values are full person names"
  },
  "anonymized_file_path": "/path/to/normalized_data_anonymized.csv",
  "lookup_file_path": "/path/to/isu_pii_lookup.json",
  "unique_identities_masked": 142,
  "pii_token_patterns": ["jane", "smith", "john", "doe", "alex", "chen"]
}
```

## Implementation Logic

### PII Column Detection (LLM Reasoning)

1. MUST examine each column's name against known PII indicators:
   - Person name indicators: `raised by`, `assignee`, `assigned to`, `reporter`, `created by`, `resolved by`, `closed by`, `modified by`, `owner`, `contact`, `processor`, `agent`, `engineer`, `analyst`, `requester`, `caller`, `user`, `submitter`, `approver`, `techn