build.allanninal.dev

Part 5 of 7 · Staff policy answerer series ~5 min read

How the handbook stays current

HR rewrites the leave policy on a Monday. By Monday afternoon, the assistant should be answering from the new version — not still quoting last year’s carry-over rule. An answerer that drifts out of date is worse than no answerer, because it’s confidently wrong. This post walks through the three ways the searchable index gets refreshed — a regular sync, a one-tap manual rebuild, and a gap report — and how each one keeps the answers honest about what the handbook actually says today.

Key takeaways

  • Three refresh paths: regular sync (changed docs), manual rebuild (urgent edit), gap report (the ask-HR list).
  • A sync re-reads only the docs that changed and re-embeds only the sections that moved.
  • A one-tap rebuild lets HR push an urgent policy change live in seconds.
  • The gap report turns unanswered questions into a to-do list for the handbook.
  • Every refresh is logged, so you can see exactly when a section’s answer last changed.

Three ways to refresh the index

Three ways the handbook index gets refreshed A diagram showing one source on the left flowing through a small change-detector, then branching into three refresh paths. Far left: a "Handbook in Drive" box showing the policy docs HR edits — leave policy, expense policy, code of conduct — with a change-detector below that compares each doc against the last version it indexed. The middle column shows the three branches. Branch one, Regular sync: a scheduled job runs every few minutes; for any doc whose content changed since last time, it re-reads the doc, splits it into sections, embeds only the sections that actually moved, and writes them to the S3 Vectors index, removing sections that were deleted. Branch two, Manual rebuild: HR taps a rebuild button in the admin channel after an urgent edit; the same indexer runs immediately on the named doc instead of waiting for the next scheduled sync, so a same-day policy change is live in seconds. Branch three, Gap report: a weekly job reads the question log, finds the questions that landed on ask HR, groups the similar ones, and posts HR a short list of topics staff asked about that the handbook didn't cover — a to-do list for new sections, not an index change by itself. The right side shows the convergence: every refresh writes a row to the spa-audit log with the doc, the sections touched, and a timestamp, so you can always see when a section's answer last changed. A note at the bottom: the gap report doesn't edit the handbook — it tells a human what to add, and the human stays in charge of policy. Handbook in Drive HR edits the docs [leave policy] [expense policy] [code of conduct] Path 1 Regular sync • Scheduled every few min • Re-reads changed docs • Re-embeds moved sections • Writes to S3 Vectors Path 2 Manual rebuild • HR taps rebuild button in admin channel • Indexer runs now on the named doc, live in seconds Path 3 Gap report • Weekly read of the log for ask-HR questions • Groups them → a list of topics the docs don’t cover Refresh log DynamoDB spa-audit timestamp · doc sections touched by-path The gap report doesn’t edit the handbook — it tells a human what to add. People own policy.
Fig 5. Three refresh paths, three effects. The regular sync keeps the index in step with edits. The manual rebuild pushes an urgent change live now. The gap report turns unanswered questions into a to-do list. Every refresh is logged.

Path 1: the regular sync (the one that runs itself)

The workhorse. A small scheduled job runs every few minutes. For each handbook doc, it asks Drive a cheap question: has this changed since I last looked? Drive keeps a revision marker on every file, so the job can tell at a glance which docs are new, which were edited, and which are untouched. For the untouched ones, it does nothing — no re-reading, no re-embedding, no cost. For a changed doc, it pulls the new text, splits it back into sections, and figures out which sections actually moved.

That last part matters for cost and speed. If HR fixed a typo in section 4, only section 4’s fingerprint needs recomputing; the other thirty sections are identical and get left alone. The job re-embeds only the moved sections through Titan Text Embeddings V2, writes the new fingerprints into S3 Vectors, and removes the fingerprints for any sections that were deleted. Within a few minutes of HR hitting save, the answerer is searching the new version. Nobody had to deploy anything; editing a Google Doc was the whole workflow.

Path 2: the manual rebuild (for “this changed today”)

A few-minute sync is fine for routine edits. But sometimes a policy changes and everyone needs the new answer now — the office is closing early for a storm, the expense limit just dropped, the on-call rule changed this morning. Waiting even five minutes feels wrong when the question is already coming in.

So there’s a manual rebuild. In a private admin channel, HR taps a “rebuild now” button and picks the doc (or rebuilds everything). The same indexer runs immediately on that doc instead of waiting for the next scheduled pass. The new sections are live in seconds. It’s the same machinery as the regular sync, just triggered by a person instead of a clock — the escape hatch for the day a policy can’t wait.

Path 3: the gap report (the handbook’s to-do list)

The first two paths keep the index in step with the docs. The third path keeps the docs in step with reality. Every week, a job reads the question log from Part 4 and pulls out the questions that landed on “ask HR.” Those are the questions the handbook couldn’t answer — either because the policy genuinely isn’t written down, or because it’s written in a way the search couldn’t find. The job groups the similar ones (lots of people asking about parental leave in different words become one line) and posts HR a short, ranked list: “these are the topics staff asked about this week that the handbook doesn’t cover well.”

Crucially, the gap report doesn’t edit the handbook. It can’t — writing policy is a human’s job, and a system that quietly invented a parental-leave rule because people kept asking would be the exact failure this whole series is built to avoid. The report just surfaces the gap. A person decides whether to add a section, and when they do, Path 1 picks it up. Over a few months, the handbook gets measurably better at answering the questions people actually have, because the questions people actually have are now visible.

Every refresh is logged, every answer is traceable

Each of the three paths writes a row to a refresh log: which doc, which sections were touched, which path triggered it, and when. That log answers a question that comes up more than you’d think: “when did the answer to this change?” If someone says “the assistant told me 15 days last month and 12 today,” you can look and see that the leave policy was edited on the 3rd and re-indexed at 9:14am, and the answer changed because the policy did — not because the assistant drifted. The index is never a black box; it’s a mirror of the docs, with a timestamped history of every time the mirror was wiped clean.

Next post: the cost breakdown. The whole pipeline above — intake, search, answer, and keeping the index fresh — runs in coffee-money territory at SMB volume. Part 6 explains exactly where the dollars go.

All posts