NPS Comment Themer

What this skill does

Takes NPS survey responses (with score 0-10 and an open-ended comment) and produces a ranked list of pain themes, weighted by detractor share. Each theme cites 2-3 verbatim quotes and the score distribution.

Inputs

• nps_path: CSV with score, comment, segment? columns.
• Optional min_theme_size: minimum responses per theme (default 5).
• Optional segment_filter: a segment value to subset the analysis.

Steps

1. Read the CSV. Validate scores are integers 0-10. Drop rows with empty comments.
2. Tag each row: 0-6 = detractor, 7-8 = passive, 9-10 = promoter.
3. Compute the NPS: %promoters - %detractors.
4. Pre-process comments: lowercase, strip punctuation, remove stopwords. Keep originals for quoting.
5. Vectorize with TF-IDF (n-grams 1-2). Run k-means with k auto-selected on the elbow.
6. Per cluster, compute: total count, detractor share, promoter share, and a "pain weight" = detractor_share * count / total_detractors.
7. Pick a name per cluster from the top 5 TF-IDF terms (noun phrases preferred).
8. Pick 2-3 quote excerpts per cluster, prioritizing detractor responses for pain themes.
9. Drop clusters with count < min_theme_size; redirect to "Other".
10. Sort themes by pain_weight descending; render markdown.

Output

nps-themes.md with: NPS header, theme table (name, count, detractor%, promoter%, pain_weight), a per-theme detail section with quotes, and an "Other" appendix. Plus nps-themed.csv mapping each row to a theme.

Verification

Recompute NPS from raw scores and confirm it matches the report header. Sample 10 themed responses by hand and check theme assignment correctness; expect >= 80% agreement. For the top 3 pain themes, confirm at least 60% of the quoted respondents are detractors. If detractor share within a theme is below 30%, the theme is not really a pain theme — reclassify under "Praise" or "Mixed".

Edge cases

• Highly templated comments (e.g., copy-pasted): dedupe by exact match before clustering to avoid one fake mega-theme.
• Comments in multiple languages: cluster per detected language; do not mix.
• NPS surveys without comments (just scores): exit early; this skill needs comments.
• Very small samples (under 30 detractors): cluster output is unreliable; emit a "low confidence" warning and just list verbatim quotes grouped by score band.