FAQ Builder

---
name: faq-builder
description: "Turn a list of conversation IDs (xlsx or csv) into a general FAQ / Q&A knowledge base using Rippit. Reads every conversation transcript through Rippit, triages each one against your categories (easy Q&A, partial rule, knowledge gap, account-specific, complex back-and-forth), generalises the recurring question-and-answer pairs, flags questions that agents answer inconsistently, keeps brand- or segment-specific answers separate, and delivers a folder of CSVs ready to review for an FAQ or an AI agent's knowledge base. Use this skill whenever the user wants to automate recurring support questions, find what an AI agent could answer from policy or process rules, build or refresh an FAQ from chats, mark \"complex\" conversations, split a large ID list into Rippit batches, or analyse a scope-of-automation file — even if they never say \"FAQ\" or \"Rippit\"."
---
# FAQ Builder

Goal: from a list of conversation IDs, produce a folder of general Q&As where the same question got the same answer, so the user can add them to an FAQ or to an AI agent's knowledge base.

Rippit does the per-conversation reading (it sees the full transcript). Claude's job is to feed it the right IDs in manageable batches, give it precise column definitions, aggregate the results, and package them. Claude does not read thousands of rows itself: that is too expensive.

## First run — make it yours

Before asking anything, LOOK at what the user actually has:
1. Run `list_data_sources` and `describe_table` on the likely conversation table. Report the source and the table you found.
2. Note which columns can satisfy each parameter below: a conversation identifier column, a timestamp column (for date windows), a grouping/segment column (brand, business unit, region), and any topic/category field. Name the real columns you see.
3. If there is no transcript-level conversation source connected, say so plainly and ask how to proceed before running the interview into a dead end.

Then ask ONE question at a time, leading with what you found and proposing a default:
1. **{{id_volume}}** — "How many IDs should we process? Default is all unique IDs; if the list is above 5,000 I can run a {{pilot_size}}-row pilot first — which do you want?"
2. **{{date_window}}** — "Do you want a date window? Default is no filter, but a common choice is the last 2 weeks on the `<timestamp column you found>` field — any preference?"
3. **{{complex_definition}}** — "How should I define a 'complex' conversation? Default is more than 3 substantive turns of clarifying, explaining or convincing — keep that?"
4. **{{recurrence_threshold}}** — "What counts as 'same question and same answer'? Default is the pair appearing in at least 2 conversations, with one-off pairs filed separately — ok?"
5. **{{grouping_dimension}}** — "Your source has a grouping column (`<column you found>`) that isn't in the answer text — should I export it with the final data so answers can be split by it?"
6. **{{triage_categories}}** — "The author's version triaged each conversation as: easy Q&A, partial (generic rule only), knowledge gap, account-specific, complex, other. Do these categories work for you, or do you want your own set?"

After the interview, restate the filled-in bindings for confirmation, then run. On later runs, reuse the established bindings unless the user asks to change them.

## Constraints that shape the workflow

Tell the user these up front, not after hitting them.

| Constraint | What to do |
|---|---|
| Spreadsheets often have huge blank tails | Run `scripts/prep_ids.py` first; report real, unique and duplicate counts |
| Rippit has no bulk ID import for transcripts; IDs go into an `IN` filter typed into the tool call (~8 tokens per ID, and the result echoes them back) | Batches of about 1,000 IDs per `create_worksheet` call |
| A worksheet holds at most 10,000 rows | Split larger lists into several worksheets |
| A share of IDs may be missing from Rippit (sync gap) | Ignore them; report the found rate |
| `get_enrich_status` and `read_table` return big payloads | Poll once per sheet; read at most 20 rows at a time; prefer `aggregate_table` / `pivot_table` |
| Large Rippit results are returned inline, never written to disk | You cannot parse them in bash; only type back what you need |
| The export link opens a login-gated web page; the sandbox cannot download the file | Tell the user to download the full export from Rippit while logged in; build only curated CSVs yourself |
| Claude.ai has no sub-agent tool | Say so. Parallelism comes from Rippit enrichment running rows in parallel and from separate worksheets |
| Rippit tools may return "No approval received" | Retry once; if it persists, tell the user an approval prompt is pending |

Untested shortcut: `upload_csv` lets the user upload the ID CSV themselves, which saves the token cost of typing IDs. It only helps if Rippit links uploaded rows to transcripts. Test it on 5 rows before relying on it.

## Workflow

### Step 1. Prepare the IDs
```bash
python scripts/prep_ids.py /mnt/user-data/uploads/<file>.xlsx --out-dir /home/claude/work
python scripts/prep_ids.py /mnt/user-data/uploads/<file>.xlsx --out-dir /home/claude/work --slice 0:300
```
The first command prints real/blank/duplicate/unique counts and writes `ids_all.json` and `unique_ids.csv`. The second prints a JSON array to paste into an `IN` filter. Excel often stores IDs as floats; the script converts them to exact-length strings.

### Step 2. Find the source table
`list_data_sources`, then `describe_table`. Identify the conversation table's string identifier column, a timestamp column, your {{grouping_dimension}} column and any topic/category field. Use its id as `tableId` below.

### Step 3. Create worksheets
`create_worksheet` with `where` = `[{"columnId":"<id column>","operator":"IN","value":[...ids as strings...]}]`. If {{date_window}} is set, add `{"columnId":"<timestamp column>","period":{"n":-14,"unit":"days"}}`. Pass the first call's `workbookId` into later calls so all sheets live in one workbook. Keep a pilot of about 300 IDs first: check the found rate and that the columns look right before scaling.

### Step 4. Triage enrichment
Run `enrich_worksheet` with the columns in `references/enrichment-triage.md`, using the categories in {{triage_categories}} and the definition in {{complex_definition}}. Poll `get_enrich_status` until `done: true`. The status result already contains answer aggregates: read them instead of reading rows.

### Step 5. Split into batches without retyping IDs
`create_worksheet` accepts a worksheet id as `tableId`, and the new sheet keeps the enrichment columns. To make N equal batches from one sheet:
1. Get boundary IDs: `read_table` with `columnIds:["<id column>"]`, `limit:1`, `offset:<k*size>`, `orderBy:[{"columnId":"<id column>","direction":"desc"}]`.
2. For each batch, `create_worksheet` from that worksheet with `<id column> > X` and `<id column> <= Y` (if IDs have equal length, string comparison works).

### Step 6. FAQ generalisation enrichment
Run the five columns in `references/enrichment-faq.md` on every batch (same instructions on each, so results are comparable). Poll each job.

### Step 7. Aggregate and decide
From the status aggregates (and `pivot_table` on FAQ Topic x Answer Key if needed):
- **Recurring and consistent:** same topic, same answer key, at least the number of conversations in {{recurrence_threshold}}. Write one canonical question and one canonical answer built only from wording agents actually used.
- **Inconsistent:** same topic, different answers (different time frames, numbers, processes). Do not pick a winner. List the variants with approximate counts and the decision needed.
- **Brand/segment specific:** promotions, limits and amounts that vary by {{grouping_dimension}}. Keep in their own file with a "verify per segment" note.
- **Single occurrence:** lowest confidence, separate file. If only the answer key was captured and not the wording, say so in the Notes column.
- Treat answer keys as approximate: wording varies. Mark counts "about" or ">=" when they come from keys.

Read at most a handful of representative rows (`read_table`, `limit` up to 5, filtered with `where`) when you need exact wording for a canonical answer.

### Step 8. Build the folder
Write a spec JSON and run:
```bash
python scripts/build_faq_folder.py spec.json --out-dir /mnt/user-data/outputs/FAQ_General_QA
```
The spec format is in `references/output-format.md`. The script writes the CSVs, a README and a zip. Then call `present_files` with the zip and each file.

### Step 9. Verify and report
- Read 3 to 10 transcripts with `read_conversations` for the labels you rely on most (a "complex" case, a knowledge gap, a canonical answer). Report what you checked.
- Report the totals: conversations enriched, found rate, FAQ-eligible share, top topics, conflicts.
- Say plainly what is not covered (unprocessed IDs), that answers come from agents and were not checked against official policy, and that the full data lives in the Rippit sheets (give the workbook link).

## Definitions

- **Complex?** Follow {{complex_definition}}. By default, `Yes` only with more than 3 substantive turns on the same issue after the first full answer. Do not count bot menu taps, greetings, holding messages, thanks or auto-close notices. A loose definition flags far too many chats as complex; keep it strict.
- **Q&A Candidate:** one of the labels in {{triage_categories}} (default: `Yes - easy Q&A`, `Partial - generic rule only`, `No - knowledge gap`, `No - complex`, `No - account-specific`, `No - other`). "Partial" matters: most real conversations are account-specific but still contain one reusable rule.
- In the triage, put the word `complex` at the start of Notes/Comment for every complex conversation.

## Side findings to flag, not to fix

- Watch for agent behaviour your team treats as a compliance matter (for example offers made in sensitive situations). Mark with `[CHECK]` and tell the user; this is for them to review, not for you to fix.
- The AI agent or a human failing a simple policy question (knowledge gap): list these as FAQ gaps.
- Do not add compliance disclaimers to FAQ answers; the user's organisation has its own. Only flag the wording that needs review.

## Reporting template

Lead with the numbers and the folder. Then: conflicts that need a decision, what was verified, what was not, confidence, and one question about next steps (for example running the remaining IDs). End every report with an explicit confidence estimate and what was NOT verified.