# How we turn resolved tickets into KB articles

The ticket-to-KB agent we run on Kortix — clusters resolved Plain support tickets for recurring questions with no matching help-center article, drafts the top gaps as real articles from the actual resolutions, and opens a PR for a human to review and publish.

Canonical page: https://openchatly.com/use-cases/ticket-to-kb

Every support team answers the same question more than once before anyone
writes it down. An agent resolves a ticket, the customer is happy, and the
answer disappears back into the support queue instead of becoming a help
article. Weeks later the same question comes in again, gets solved the same
way, and disappears again. The knowledge was generated a dozen times over; it
was never captured once.

We run a ticket-to-KB agent on Kortix that reads our resolved Plain tickets
every week, finds the questions that keep recurring with no article to answer
them, and drafts the highest-value gaps as real articles pulled from how we
actually solved them — then opens one PR. This is how new KB coverage gets
written from what our support queue already knows.

- **Team:** Kortix
- **Runs on:** Weekly cron · reusable session
- **Connected systems:** Plain · GitHub (docs/KB repo)
- **Mode:** Draft-only · one PR per run

## The problem

The knowledge exists — it's sitting in hundreds of resolved Plain threads —
but nobody has time to mine it. A support lead reviewing tickets for KB gaps
manually has to remember which topics were already covered, which recurring
questions are worth an article versus a one-off, and then actually write the
draft from scratch. That review happens rarely, if at all, and by the time it
does, the backlog of recurring-but-undocumented questions is large enough that
picking where to start is its own project.

A generic AI writer pointed at "write some help articles" doesn't fix this
either — it has no memory of what's already covered and nothing grounding its
drafts in how the team actually resolves the issue, so it either duplicates
existing articles or writes generic copy that doesn't match a real resolution.

## What we built

On Kortix, a weekly cron re-prompts the same persistent session — a cloud
sandbox that resumes its own ledger rather than starting cold. Each run it
reads recently resolved threads from Plain, clusters them into recurring
topics, checks each topic against both the KB repo's existing articles and its
own ledger of topics already drafted, and picks the top gaps: recurring
questions with real ticket volume and no article. It drafts each one from the
actual resolutions used in those tickets, then opens a single PR against the
docs repo. Nothing publishes without a human merge.

## 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 mining 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 ticket-to-KB agent in this workspace.

1. Create the agent agents/ticket-to-kb.md. Its job is to turn resolved support tickets into draft knowledge-base articles. It may use the PLAIN_API_KEY and GH_TOKEN secrets.

2. Create the skill skills/kb-gap-mining/SKILL.md with these rules:
   - Read memory/kb-gap-mining-log.md first. Skip topics already covered or already in an open KB pull request.
   - Read resolved threads from Plain, read-only, and cluster them into topics by intent, not wording.
   - A topic is a gap only when it recurs and has no article under content/kb in owner/docs. A single ticket never justifies a draft.
   - Draft the top 3 to 5 gaps from the real resolutions only. Strip every customer name and account detail.
   - Open one pull request against owner/docs with the ticket count per article. Never merge it and never publish.
   - Write only under content/kb, and add this run's topics to the ledger.

3. Add a cron trigger weekly-kb-gap-mining to kortix.yaml. It runs the ticket-to-kb agent every Monday at 08:00 with the prompt "Load the kb-gap-mining skill and run one complete ticket-to-KB mining pass."

4. Tell me which of these secrets are not set yet.

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

### Connect your tools

Add a read-only Plain API key and a GitHub token for your docs repo as workspace
secrets. Both are encrypted and injected into the session at runtime, scoped to
this agent.

- **Plain** (Required):
Reads recently resolved support threads, read-only.
- **GitHub** (Required):
Checks the KB repo for coverage and opens a draft PR.

### Run it once with this prompt

Merge the change request, then start a session with the **ticket-to-kb** agent
and send this prompt. Read the drafted articles in the pull request before you
let the schedule take over.

**Prompt**

```
Run one ticket-to-KB pass.

1. Read memory/kb-gap-mining-log.md and any open KB pull request in owner/docs.
2. Read the threads resolved in Plain in the last 7 days. Do not change any thread.
3. Cluster them into topics, and find the topics that recur and have no article under content/kb.
4. Draft up to 5 articles from the real resolutions, with every customer detail removed.
5. Open one pull request against owner/docs with the ticket count per article. Do not merge it.
6. Update the ledger.
```

### Let the weekly schedule take over

The change request added this trigger to `kortix.yaml`. From now on the agent
runs every Monday at 08:00. It reads its ledger in memory first, so a topic
already drafted is never drafted again. To change the time, edit the cron line,
or open **Triggers** in the workspace.

**kortix.yaml**

```yaml
triggers:
  - slug: weekly-kb-gap-mining
    name: Weekly ticket-to-KB mining
    on:
      cron: "0 0 8 * * 1"
    run:
      agent: ticket-to-kb
      prompt: Load the kb-gap-mining skill and run one complete ticket-to-KB mining pass.
```

### A person merges every article

The agent opens one pull request on its own branch and stops. It never pushes to
the live docs branch, never merges and never publishes. A person reviews the
drafts, edits them and merges what is ready. Plain stays read-only, so the agent
cannot reply to or close a ticket.

### Read the weekly pull request

Each run ends with one pull request and an updated ledger. This is what a run looks like
in the session:

> **Weekly ticket-to-KB mining · Mon 08:00**
>
> Prompt: Load the kb-gap-mining skill and run one complete ticket-to-KB mining pass.
>
> Read **214** resolved threads and found **17** recurring topics. **4** had
> enough volume and no article, so I drafted them in one pull request. **3**
> topics stay in the ledger below the bar.

> **The pattern**
> A weekly **cron** resumes one persistent **session** that reads a durable
> **ledger** of covered topics, clusters resolved Plain tickets read-only, and
> opens a single GitHub **pull request** of drafted articles — never publishing
> and never merging on its own.

## Make it do more

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

**Find stale articles**

```
In a separate section of the pull request, list existing articles under content/kb whose steps no longer match how recent tickets were resolved.
```

**Separate product gaps**

```
When a topic is a bug or a missing feature, not a how-to, list it in the pull request description instead of drafting an article.
```

**Learn from review**

```
After a KB pull request merges, compare the merged articles to your drafts and write the edits into the drafting rules in memory.
```

## Guardrails

Turning support history into published documentation is a one-way trust
question — from tickets to drafts is safe, from drafts to a live article is
not something the agent decides — so the guardrails are built around that
line:

- **Isolation.** Every run resumes in its own isolated sandbox. The session is granted access only to Plain and the KB repo, and only the pull request is written back out.
- **Scoped secrets.** The Plain API key and the GitHub token are encrypted in
  the Secrets Manager and injected into the sandbox at runtime, scoped to the agents you grant them to.
- **Draft-only.** The agent opens a PR against an isolated branch and stops.
  It never pushes to the live docs branch and never merges its own work — a
  human reviews and publishes.
- **Read-only tickets.** Plain access is read-only; the agent cannot edit,
  close, or reply to a ticket while mining it for KB content.
- **Everything is code.** The agent's clustering rules, drafting standard, 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:** Resolved tickets reclustered against the current KB gap set
- **Draft-only:** Every article ships as a PR a human reviews and merges
- **1 ledger:** Tracks which topics are covered so nothing is redrafted

The backlog of "we keep answering this but never wrote it down" questions now
arrives as a small, reviewable PR each week, with every draft traceable back to
the real tickets that produced it. The agent only clusters and drafts; the
support team decides what gets published.
