> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forepost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes

> Track repeated topics across conversations. When a theme crosses its weekly threshold, Forepost can auto-file a Linear bug.

Most CX leaders already know CSAT is down. The harder question is *what keeps coming up*. **Themes** is Forepost's answer: a small surface that tracks repeated topics over weeks and tells engineering when a topic stops being noise.

## What a theme looks like

Each theme is a workspace-scoped row with:

<CardGroup cols={2}>
  <Card title="Label and slug" icon="tag">
    Human name ("Billing portal access"), auto-slugged for dedup.
  </Card>

  <Card title="Description" icon="quote-left">
    One sentence on what the theme covers.
  </Card>

  <Card title="Status" icon="circle-dot">
    `emerging` · `tracked` · `resolved` · `dismissed`.
  </Card>

  <Card title="Auto-Linear threshold" icon="bug">
    Mentions per week before Forepost files a Linear bug. Default 10.
  </Card>
</CardGroup>

A companion table records `theme_mentions` per ISO week. A mini-bar on each card shows the last 8 weeks at a glance.

## Three ways to add mentions

<Steps>
  <Step title="Manual +1">
    Click the **+1** button on a theme card. Use this when you read a ticket and recognise it as another instance.
  </Step>

  <Step title="API call">
    `POST /themes/:id/mention` — useful from a helpdesk webhook or a tag-watcher script.
  </Step>

  <Step title="Suggested from samples">
    Click **Suggest from samples** on the Themes view to let Forepost cluster the last 7 days of worst-CSAT conversations into proposed themes. See below.
  </Step>
</Steps>

Each mention can carry an optional `ticketId`; Forepost keeps up to 5 sample ticket ids per week per theme for context.

## Model-suggested themes

<Note>
  Requires a connected Intercom workspace.
</Note>

Click **Suggest from samples** on the Themes view. Forepost pulls the last seven days of low-CSAT (rating ≤ 3) conversations from Intercom, runs them through a Haiku clustering prompt with strict JSON output, and proposes up to three distinct themes.

Suggestions are **not auto-created** — the leader stays in control. Each card shows:

* The proposed label and one-sentence description
* An estimated mention count from the sample
* 1–3 example topics from the sample that fed the cluster

Two buttons per suggestion:

<CardGroup cols={2}>
  <Card title="Track" icon="check">
    Creates the theme via `POST /themes` with the default threshold of 10. Shows up in the regular Themes grid.
  </Card>

  <Card title="Dismiss" icon="xmark">
    Removes the suggestion from this view. Doesn't blacklist — it can return on the next suggest pass.
  </Card>
</CardGroup>

Themes already in your workspace are filtered from suggestions, so re-running won't re-propose `billing-portal-access` if you already track it.

<Warning>
  Rate-limited at 6 suggest calls per hour per workspace.
</Warning>

## Auto-filing to Linear

<Note>
  Auto-filing requires a connected Linear integration. See [Linear](/help/linear).
</Note>

When the current ISO week's mention count crosses `auto_linear_threshold` AND the theme doesn't already have a Linear issue id, Forepost calls Linear's GraphQL `issueCreate` mutation with:

* **Title:** `[CX theme] <label> — N mentions this week`
* **Description:** *Auto-filed by Forepost because this theme crossed `N` mentions in week `YYYY-Www`. Review in Forepost → Themes.*

The first team in your Linear workspace is used. The created issue's identifier (e.g. `ENG-123`) is stored on the theme row and the status flips to `tracked`. Subsequent mentions don't re-file.

## How themes feed the brief

When themes exist with non-zero mentions in the current or previous ISO week, the brief context includes:

```
EMERGING THEMES (last 14 days):
• Billing portal access — 14 mentions this week (up from 2). Linear ENG-481 filed.
• Slack export — 6 mentions, sustained across 3 weeks
• Webhook retries — 3 mentions (new this week)
```

The brief is told to call out emerging themes by name when they correlate with CSAT or volume movement.

## API

```bash theme={null}
GET    /themes                   # list with last 8 weeks of mentions per theme
POST   /themes                   # create — body { label, description?, autoLinearThreshold? }
POST   /themes/suggest           # owner/admin: cluster recent worst-CSAT into 1-3 suggested themes
PATCH  /themes/:id               # edit label / description / status / threshold
POST   /themes/:id/mention       # increment current ISO week — body { count?, ticketId? }
DELETE /themes/:id               # soft-archive
```

## Privacy

Themes are workspace-scoped. Sample ticket ids are stored but not conversation bodies. If you uninstall Linear, previously-filed issues stay there (Forepost can't delete them); the `linear_issue_id` on the theme row remains as a breadcrumb.