# How we turn NPS responses into themes

A weekly cron reads new NPS/CSAT survey responses from a Google Sheet, clusters them into themes with sentiment and detractor drivers, and posts the score trend and representative quotes to Slack.

Canonical page: https://openchatly.com/use-cases/nps-analysis

NPS and CSAT surveys generate a response every time someone answers, and most of
it goes unread. The score gets tracked in a dashboard, but the comment next to it
— the actual reason someone gave a 4 instead of a 9 — sits in a spreadsheet row
and never gets aggregated with the hundred other comments saying the same thing.
By the time a theme is obvious to a human skimming the sheet, it's been building
for months.

We run an NPS analysis agent on Kortix that reads new survey responses every week
and posts the themes, sentiment, and detractor drivers to our customer-success
Slack channel, alongside how the score moved since last week. It only reads the
survey sheet; the single output is the Slack post. This is how we keep our own
NPS program from turning into an unread spreadsheet.

- **Team:** Kortix
- **Runs on:** Weekly cron
- **Connected systems:** Google Sheets · Slack
- **Mode:** Read-only · one Slack post per week

## The problem

Every NPS or CSAT response is really two signals: a number and a comment. The
number is easy to track — most survey tools already chart it. The comment is
where the "why" lives, and it's the part that gets lost. Free-text feedback piles
up in a spreadsheet export, one row per response, and nobody reads all of it every
week, so the same complaint from a dozen different detractors never gets counted
as one thing.

The common approaches don't fix this. A dashboard shows the score moving without
saying why. Someone skimming the sheet manually catches the loudest complaint, not
the most common one, and does it inconsistently from week to week. And because
nothing tracks the theme over time, a driver that's been growing for a month looks
identical to one that appeared once and went away.

## What we built

On Kortix, a weekly cron triggers an agent. It spawns an isolated session (a cloud
sandbox) with read-only access to the Google Sheet the survey tool exports
responses into, reads the full response history, clusters the free-text comments
into themes, tags each response's sentiment and score band, isolates what's
actually driving detractors this week, and computes how the score has moved
week over week. It posts one summary to Slack with representative quotes. It
writes nothing back to the sheet.

## How it works

### Copy the setup prompt into a new session

Open your Kortix workspace, start a new session, paste this prompt and send it.
The agent writes the agent file, the theme analysis skill and the weekly trigger, and
opens a change request for you to review. Prefer clicks? Choose **Use this
template** instead.

**Setup prompt**

```
Set up a weekly NPS analysis agent in this workspace.

1. Create the agent agents/nps-analysis.md. Its job is to turn NPS and CSAT survey responses into themes, detractor drivers and a score trend. It may use the Google Sheets connector and post to Slack.

2. Create the skill skills/nps-theme-analysis/SKILL.md with these rules:
   - Read the full response history in the NPS responses sheet every run. Never write to the sheet.
   - Band NPS scores as promoter 9 to 10, passive 7 to 8 and detractor 0 to 6. Tag the sentiment of each comment from its text.
   - Cluster comments into themes by meaning, not wording, and pick one or two representative quotes for each theme.
   - Rank this week's detractor themes by count, and flag any driver that is new or growing against prior weeks.
   - Post one summary to #customer-success. Never contact a respondent and never open a ticket.

3. Add a cron trigger weekly-nps-analysis to kortix.yaml. It runs the nps-analysis agent every Monday at 09:00 with the prompt "Load the nps-theme-analysis skill and run one complete NPS/CSAT analysis sweep."

4. Tell me which of these connectors are not connected yet.

5. Open a change request with all of it. Do not merge it.
```

### Connect your tools

Open **Connectors** in your workspace and connect the sheet your survey tool
exports into, and Slack. Credentials are brokered server-side and never enter
the agent's machine.

- **Google Sheets** (Required):
Reads the week's survey responses, read-only.
- **Slack** (Required):
Posts the theme summary with representative quotes.

### Run it once with this prompt

Merge the change request, then start a session with the **nps-analysis** agent
and send this prompt. Check the themes against a sample of comments before you let
the schedule take over.

**Prompt**

```
Run one NPS analysis on the NPS responses sheet.

1. Read every response in the sheet. Do not write to it.
2. Band each score as promoter, passive or detractor, and tag the sentiment of each comment.
3. Cluster the comments into themes across the full history, with a count and a quote for each.
4. List this week's top detractor drivers and say which are new or growing.
5. Compute this week's score and its move since last week, and post the summary to #customer-success.
```

### Let the weekly schedule take over

The change request added this trigger to `kortix.yaml`. From now on the agent
runs every Monday at 09:00, each run in a new session on its own cloud computer.
To change the time, edit the cron line, or open **Triggers** in the workspace.

**kortix.yaml**

```yaml
triggers:
  - slug: weekly-nps-analysis
    name: Weekly NPS/CSAT analysis
    on:
      cron: "0 0 9 * * 1"
    run:
      agent: nps-analysis
      prompt: Load the nps-theme-analysis skill and run one complete NPS/CSAT analysis sweep.
```

### Report only, never act

The agent reads the sheet and writes one Slack post. It never edits a row,
never contacts a respondent and never opens a ticket. What to do about a theme
stays with the customer-success team.

### Read the weekly report

Each run ends with one report in the channel. This is what a run looks like
in the session:

> **Weekly NPS/CSAT analysis · Mon 09:00**
>
> Prompt: Load the nps-theme-analysis skill and run one complete NPS/CSAT analysis sweep.
>
> NPS is **41**, down **6** points from last week, because of more detractors
> rather than fewer promoters. The top detractor driver is slow support replies,
> with **9** mentions this week, up from **3**. Onboarding friction is a new
> theme with **4** mentions.

> **The pattern**
> A weekly **cron** spawns a fresh session with a read-only **connector** into the
> survey Google Sheet. The clustering and scoring rules live as **skills** and
> **memory**. The agent reads the full history every time and writes nothing but
> the Slack post.

## Make it do more

Once it works, paste any of these into the same session.

**Split the score by plan**

```
When the sheet has a plan or segment column, add this week's score and top themes per segment to the summary.
```

**Monthly theme review**

```
On the first Monday of each month, post the top five themes of the last month and how each one moved to #customer-success.
```

**Name the right owner**

```
Next to each theme that names a product area, mention the owner of that area from memory so the right person sees it.
```

## Guardrails

The agent reads a live survey export, so its access is scoped and one-directional:

- **Isolation.** Every run happens in its own isolated sandbox. The session is granted access only to the sheet it's scoped to, and only the Slack post is written back out.
- **Scoped secrets.** The Google Sheets and Slack credentials are encrypted in the
  Secrets Manager and injected into the sandbox at runtime, scoped to the agents you grant them to.
- **Read-only, report-only.** The connector into the survey sheet is read-only —
  the agent cannot edit a response, add a row, or write back a score — and it
  never reaches out to a respondent. It reports; it doesn't act.
- **Everything is code.** The agent's clustering rules, skills, and per-system
  permissions are files in the repo, versioned and changed through a reviewed
  **change request** rather than a dashboard setting.

## The outcome

- **Every week:** Themes and score trend recomputed from the full response history
- **Read-only:** Nothing written back to the survey sheet
- **1 post:** Score trend, themes, and detractor drivers in one Slack message

Survey comments that used to sit unread in a spreadsheet now arrive every week as
a set of named themes with quotes and counts, next to the score's actual
week-over-week move and what's driving it. The agent only reads and reports; the
team still decides what to do about each theme.
