| name | feedback-clustering |
| description | Turns feedback from Plain, public reviews, and a Slack channel into deduplicated, quantified themes, and reconciles each theme against one Linear issue in {{linear_team}} — never prioritizing, assigning, or closing. |
Feedback about the same underlying request shows up worded differently in
Plain support threads, public reviews, and a Slack channel, and never gets
counted together. This skill turns a run's raw feedback into themes —
deduplicated, quantified, and backed by real quotes — and reconciles each
theme against exactly one Linear issue in {{linear_team}}, so a request a
hundred people made looks different from a one-off.
Fresh session each run. There is no ledger — the existing Linear issues in
{{linear_team}} are the running state to reconcile against.
- The scheduled cron fires the feedback sweep.
- A human asks for the current feedback themes, or why a piece of feedback did
or didn't land in a given theme.
Step 1 — Read the existing themes in Linear first
Before touching any source, pull the current state of {{linear_team}} so new
feedback is reconciled, not duplicated:
- List open issues in {{linear_team}}, with their title, description, and
current quote/count body.
- Note each issue's theme signature — the core request it represents — not
just its title text.
Step 2 — Gather support threads from Plain (read-only)
Pull recent threads (since the last run's approximate window, or the last
24–48h if that's unknown). For each thread, extract:
- The specific request or complaint, in the user's own words.
- A candidate quote — the clearest single sentence expressing it.
- Enough context (account, thread link) to trace it back later.
Ignore threads that are pure support (bug already fixed, question already
answered) with no underlying feature request or recurring complaint.
Step 3 — Gather public reviews (read-only)
Fetch the current reviews from {{review_sources}} (G2, app-store listings, or
whatever is configured). For each new review since the last visible one:
- Extract the specific ask or complaint, not star-rating alone.
- Take the reviewer's own phrase as the candidate quote.
- Skip pure praise with no actionable request, and skip reviews already
reflected in an existing Linear issue's quotes.
Step 4 — Gather messages from the feedback channel (read-only)
Read {{feedback_channel}} for messages where a team member is relaying
something they heard from a user (not internal chatter). Treat these the same
as a support thread: extract the request and a quote, with the relaying
message as the source.
Step 5 — Cluster into themes
Group everything gathered in Steps 2–4 into themes. Two mentions are the
same theme when they ask for the same underlying capability or fix, even
if:
- The wording is completely different ("can't bulk export" vs. "no way to
download everything at once").
- They come from different sources (a Plain thread and a G2 review can be the
same theme).
- One is more specific than the other (a general complaint and a precise
technical ask can still be the same root request — cluster on intent, not
surface detail).
Two mentions are different themes when they'd require different work to
resolve, even if they sound superficially similar (e.g. "slow page load" on
the dashboard vs. "slow page load" on export — different root cause, keep
separate unless you can confirm otherwise).
Step 6 — Pick the representative quote and title
For each theme:
- Quote — the clearest, most specific verbatim quote from any mention in
the theme. Prefer a quote that names the concrete capability over a vaguer
one.
- Title — a short, action-oriented issue title describing the requested
capability or fix, not the complaint's tone (e.g. "Bulk export for
workspace data", not "Users are annoyed about exporting").
Step 7 — Reconcile against Linear
For each theme from Step 5:
- Matches an existing issue (same theme signature from Step 1): add the
new quote(s) to its quote list, increment its mention count, and note the
new source(s). Don't create a duplicate.
- No match — create a new issue in {{linear_team}} with the title, an
opening set of quotes, a mention count, and the source(s) each quote came
from.
Every issue body should always show: representative quotes (a small curated
set, not every mention verbatim), a running mention count, and which sources
(Plain / reviews / Slack) contributed.
Step 8 — Stop
Report the set of Linear issues created or updated this run. Do not set
priority, assign an owner, or close any issue — even one that looks resolved
or clearly a duplicate of another; leave that judgment to a human.
- **Read-only sources.** Plain, the review sources, and {{feedback_channel}}
are read-only. The only write in this skill is creating or updating a
Linear issue.
- **One issue per theme.** Never file a second issue for a theme that already
has one — reconcile against Step 1's list first, every run.
- **People decide priority.** The agent never sets priority, assigns an
owner, or closes an issue. It quantifies and describes; humans weigh themes
against the roadmap.
- **Quotes over volume.** Keep a curated set of representative quotes per
issue, not an ever-growing dump of every mention.
- **Scoped secrets.** Plain, review-source, Slack, and Linear access is
brokered server-side; no raw credential is ever pasted into chat.
- **No memory between runs.** Each run is a fresh session; the current state
of {{linear_team}} in Linear is the only carryover, not an internal ledger.
