Feedback Clusterer

What this skill does

Reads a CSV or text file of customer feedback responses and groups them into thematic clusters. Each theme gets a name, a count, and 2-3 verbatim quote excerpts. Themes with fewer than 3 responses are surfaced for manual review.

Inputs

• feedback_path: CSV (with a response column) or a .txt (one response per line).
• Optional min_cluster_size: minimum to be a theme (default 3).
• Optional language: defaults to en.

Steps

1. Read the file. Drop empty / single-character rows. Lowercase the text for analysis but keep originals for quoting.
2. Tokenize and remove stopwords using a small built-in stopword list per language.
3. Compute TF-IDF vectors over the tokenized responses with scikit-learn's TfidfVectorizer (or a tiny JS equivalent).
4. Run k-means with k chosen via the elbow on inertia for k in [2, 12]. Pick the smallest k whose marginal inertia improvement is below 10%.
5. For each cluster, name it: take the top 5 TF-IDF terms and form a noun-phrase label (e.g., "slow page loads").
6. Pick 2-3 representative quote excerpts per cluster: the responses closest (cosine distance) to the cluster centroid, truncated to one sentence.
7. Drop any cluster with size < min_cluster_size; place those responses in an "Other / Long Tail" bucket.
8. Sort themes by size descending.
9. Render a markdown report: H2 per theme with size, one-paragraph synthesis (not invented — drawn from common phrases), and the quote excerpts.
10. Emit a CSV feedback-clusters.csv mapping each response to its theme.

Output

feedback-themes.md plus feedback-clusters.csv. The markdown lists themes ranked by size, each with name, count, share of total, and quotes. Stdout prints the chosen k and the inertia values for each candidate k.

Verification

Re-run with k+1 and k-1 and confirm the top three themes remain stable in name and size; if they flicker, the clustering is fragile and the report should warn. Sample 10 randomly assigned responses and check by hand whether each lands in a sensible theme; agreement should exceed 80%. The "Other" bucket size must not exceed 30% — if it does, lower min_cluster_size or examine the data for noise.

Edge cases

• Very short responses ("good", "bad"): drop them or assign to a "minimal" bucket.
• Responses in mixed languages: the algorithm runs in the requested language; surface a count of responses skipped.
• Highly templated responses (e.g., scripted survey output): clustering will produce one giant theme — flag and recommend deduplication first.
• Sample size under 30: clustering is unreliable; emit a "small sample" notice and just list responses with rough tags rather than k-means.