build.allanninal.dev

Part 5 of 7 · FAQ builder series ~5 min read

How a FAQ entry gets approved

A proposed entry lands in the reviewer’s Slack at the end of the day’s run. The question, a short grounded answer, a link to the source it came from, and three buttons. What happens when they tap one? This post walks through the three things a reviewer can do — approve, edit, reject — and how the live FAQ doc, the cluster state, and the audit trail all stay in sync. This is the gate that keeps a wrong answer from ever reaching a customer.

Key takeaways

  • Three actions per proposal: approve (publish as drafted), edit (fix it, then publish), reject (drop it with a note).
  • Approve and edit write the entry to the live FAQ doc via the Docs API and mark the cluster published.
  • A published entry is added to the “already covered” set, so the grouper stops proposing it.
  • Reject keeps the cluster from coming back unless the question changes meaningfully.
  • The approve button is a Slack interactive message backed by a Function URL; every action is logged.

Three actions on a proposal

Three actions on a proposed FAQ entry A diagram showing one input on the left flowing through an interactive Slack panel, then branching into three action paths. Far left: a "Proposal in Slack" box showing the question, the drafted answer, and a link to the source, with three button placeholders below: Approve, Edit, Reject. The reviewer taps one button. The middle column shows the three branches. Branch one, Approve: a Function URL Lambda writes the entry to the live FAQ Google Doc via the Docs API, marks the cluster published in the fb-clusters table so the grouper stops proposing it, and writes an approved event to the audit trail. Branch two, Edit: opens a Slack modal pre-filled with the drafted answer; the reviewer fixes the wording and saves; the Function URL Lambda publishes the reviewer's version to the FAQ doc, keeps the original draft alongside it for comparison, and marks the cluster published. Branch three, Reject: opens a small modal asking why; on save, the Lambda drops the proposal, records the reason, and marks the cluster rejected so it won't come back unless the question changes meaningfully. The right side shows the convergence: every action writes a row to the fb-audit DynamoDB table with timestamp, cluster id, action, by-user, and a before-and-after snapshot. A note at the bottom: nothing reaches the live FAQ without a human tap — approve and edit publish, reject does not. Proposal in Slack question, answer, source [Approve] [Edit] [Reject] Action 1 Approve • Docs API writes the entry to the live FAQ doc • Cluster marked published • Grouper stops proposing it Action 2 Edit • Modal pre-filled with the drafted answer • Your version publishes; draft kept for compare Action 3 Reject • Modal asks why (short note) • Cluster marked rejected — won’t come back Audit trail DynamoDB fb-audit timestamp · cluster_id action · by-user before / after Nothing reaches the live FAQ without a human tap — approve and edit publish, reject does not.
Fig 5. Three actions per proposal, three different effects. Approve publishes the draft as-is. Edit publishes the reviewer’s version. Reject drops it with a reason. Every action writes to the audit trail, and only approve and edit reach the live FAQ.

Action 1: approve (the common case)

The reviewer reads the proposal, clicks the source link, sees the answer matches the doc, and taps Approve. The tap submits to a Function URL Lambda. Three things happen, in order. First, the Docs API inserts the entry into the live FAQ doc — a new question-and-answer section, placed in the right category, with a small footnote linking the source passage. Second, the cluster is marked published in the fb-clusters table and added to the “already covered” set, so the grouper in Part 3 will skip the same question from now on instead of proposing it again. Third, an action: approved row is written to fb-audit with the user, the timestamp, and the published text.

From the customer’s side, the next person who searches the help center for that question finds the answer waiting — no email, no wait. From your side, one more recurring question just stopped reaching the support queue.

Action 2: edit (the “almost right”)

Most drafts are close but not perfect. The answer is correct but a little stiff, or it’s missing a caveat the reviewer knows matters, or the phrasing could be warmer. The reviewer taps Edit. A Slack modal opens pre-filled with the drafted answer. They fix the wording and hit Save.

The Function URL Lambda publishes the reviewer’s version to the FAQ doc, not the model’s. It keeps the original draft alongside the published version in the audit row, so later you can see what the model proposed and what a human changed — useful for tuning the voice doc if the same kind of edit keeps happening. The cluster is marked published exactly like the approve path. Edit is the path that quietly trains the system: when reviewers keep softening the same phrase, that’s a hint to add it to the voice doc’s banned list so the next draft already avoids it.

Action 3: reject (the “not this”)

Sometimes the proposal shouldn’t exist. The question is a one-off the grouper over-counted. The answer touches something you’d rather not put in a public FAQ (pricing exceptions, a workaround for a bug you’re fixing). The source the model grounded in is itself out of date. The reviewer taps Reject and a small modal asks why — a short note, picked from a few common reasons or typed freely.

On save, the Lambda drops the proposal, records the reason in the audit trail, and marks the cluster rejected. A rejected cluster won’t come back as a candidate unless the underlying question changes meaningfully — the grouper checks whether new asks have drifted far enough from the rejected cluster’s center to count as a genuinely different question. That keeps a reviewer from having to reject the same thing every week, while still letting a real new question through.

Every action is logged, every change is reversible

The fb-audit table records every approve, edit, and reject with the user who acted, the timestamp, and a snapshot of the entry before and after. If a wrong answer gets published — a reviewer approved too fast, or a source turned out to be stale — a rep can run an “unpublish” through a small admin command that removes the entry from the FAQ doc and reopens the cluster. The unpublish is itself an audit row, so the trail stays clean.

This reversibility matters because a FAQ is a living document edited by different people over months. The next person to touch the warranty answer might be a teammate who wasn’t here when it was written. The audit trail — who approved it, from which source, and what it said before — is the only memory they have, and it’s the difference between confidently updating an entry and being afraid to touch it.

Next post: the cost breakdown. The whole pipeline above runs in coffee-money territory at SMB volume; Part 6 explains exactly where the dollars go and why the embeddings, not the drafting model, are the biggest line.

All posts