kb-with-receipts

---
name: kb-with-receipts
description: A reusable, tool-agnostic method for turning scattered product/operations documents, design files, and tutorial videos into a clean, citation-grounded, queryable knowledge base — built once as Single-Source-of-Truth Markdown and served through two outputs (a no-code Q&A tool such as NotebookLM + a reusable Claude Skill). Every answer can point back to the exact source it came from. Use when someone wants to build an internal "ask-anything" assistant for ops/support/PM teams, consolidate messy docs into a sourced knowledge base, set up a low-maintenance monthly-updated KB, resolve cross-file contradictions, run an adversarial integrity audit, ground answers in a real database schema, or wants the QA / anti-hallucination workflow for a document Q&A system.
---

# kb-with-receipts — Sourced Knowledge Base Builder

A battle-tested method for "growing" an assistant that answers questions about your product/operations **and cites where every answer came from**. Distilled from a real internal deployment (anonymized) that took ~300 scattered source files to a **97%-correct, zero-hallucination, fully-traceable** Q&A knowledge base.

This Skill is the **method**, not a specific knowledge base. Use it to build your own.

---

## The core idea (read this first)

> **Maintain ONE clean set of structured Markdown (the Single Source of Truth), and feed it to TWO outputs.**

1. **A no-code Q&A tool** (e.g. NotebookLM) — for non-technical teammates to ask questions by typing. Picked because it gives inline, click-back-to-source citations, has zero learning curve, and costs ~nothing.
2. **A reusable Claude Skill** (`SKILL.md` + `references/`) — for advanced queries and automation.

Update only the SSOT → both outputs stay in sync. Never maintain two copies of the truth.

**Four non-negotiable principles** (the source of the quality):
- **Extractive, not abstractive** — move and reorganize text; never paraphrase facts. Numbers, amounts, dates, rules, field names, status codes are copied **verbatim**. Abstractive rewrites read nicely but hallucinate; for ops/spec knowledge, factual consistency beats fluency.
- **Per-section source tags** — every section starts with `> Source: {original-filename} | {date}`. This both improves retrieval (contextual retrieval) and lets the Q&A tool surface real provenance.
- **Time-ordering as conflict resolution** — when a topic has multiple versions, the **newest** wins; older versions only backfill gaps the new one didn't cover, with the evolution explicitly annotated.
- **Faithful-to-source ≠ correct** — source docs may contain drafts, cross-contaminated requirements, or unimplemented "vision" items. Verbatim consolidation drags these in. Only a domain expert sampling answers can catch them → recycle every catch into the regression test bank.

---

## The pipeline at a glance

Build it like training a new librarian: give clean material, then test, correct, and fill gaps.

| Stage | What | Reference |
|---|---|---|
| 0 | **Inventory & taxonomy** — list every source, flag empties/drafts/dupes, bucket topics mutually-exclusively | `references/02-technical-pipeline.md` |
| 1 | **Consolidate text** (parallel agents) — dedupe, time-order, extractive move, source-tag each section | `references/02-technical-pipeline.md` |
| 2 | **Videos → text** — scene-change frames + transcript → timestamped illustrated steps | `references/02-technical-pipeline.md` |
| 3 | **Design files → text** — REST API render of screens → read visually → write text specs | `references/02-technical-pipeline.md` |
| 4 | **Publish to the Q&A tool** — programmatic upload, split by audience | `references/05-qa-tool-gotchas.md` |
| 5 | **QA loop** — ask the most likely questions, grade vs. source, fix, re-test | `references/03-qa-and-audit.md` |
| 6 | **Integrity audit** — three-way cross-check to kill "source has it, KB missing it" gaps | `references/03-qa-and-audit.md` |
| ∞ | **Monthly update** — re-export, auto-refine, sync; human only arbitrates conflicts & samples | `references/04-monthly-update-sop.md` |

For the plain-language "why" and the tool-selection rationale, read `references/01-method-overview.md`.

---

## Routing table — which reference to load for which job

| If the user wants to… | Read |
|---|---|
| Understand the approach / decide if it fits | `references/01-method-overview.md` |
| Actually condense raw docs/design/video into a KB | `references/02-technical-pipeline.md` |
| Set up the QA loop and integrity audit | `references/03-qa-and-audit.md` |
| Keep the KB fresh every month | `references/04-monthly-update-sop.md` |
| Avoid the Q&A tool's silent quality killers | `references/05-qa-tool-gotchas.md` |
| **Resolve "two files say different things"** contradictions | `references/06-consensus-pages.md` |
| **Audit the whole KB adversarially** before shipping | `references/07-adversarial-audit.md` |
| **Turn the KB into a chat bot + a correction loop** | `references/08-correction-flywheel.md` |
| **Serve non-technical and technical users from one KB** | `references/09-audience-adaptive-answers.md` |
| **Answer "does our database support feature X?"** | `references/10-schema-grounding.md` |
| **Let an agent safely edit the KB (verified)** | `references/11-maker-verifier-loop.md` |
| **Give the KB a chat-app (LINE) face — only after Q&A works** | `references/12-notebooklm-line-bot.md` |

---

## When you apply this Skill, do this

1. **Start with the overview** (`references/01-method-overview.md`) to confirm the approach fits the user's situation (do they need citations? non-technical audience? low maintenance?). If a fully-custom RAG or an enterprise search platform is genuinely warranted, say so.
2. **Inventory before building** — never start consolidating before Stage 0 taxonomy is done; it's what prevents the same file being processed twice.
3. **Enforce the four principles** on every consolidated file. The single most common failure is silently paraphrasing a number.
4. **Resolve contradictions with consensus pages** (`references/06-consensus-pages.md`) instead of silently picking one side — add an authoritative concept page and backlink the sources.
5. **Always run the QA loop, the integrity audit, and the adversarial audit** before declaring done (`references/03` + `references/07`) — "it answers" is not "it answers correctly and completely."
6. **Mind the Q&A-tool gotchas** (`references/05-qa-tool-gotchas.md`) — e.g. NotebookLM silently drops fenced code blocks; run `scripts/make_nlm_upload.py` on any file containing code/SQL/JSON before uploading.
7. **Hand off a monthly update SOP and a correction flywheel** (`references/04` + `references/08`) — this is a living asset, not a one-shot deliverable.
8. **If an agent will edit the KB unattended**, run it as a maker/verifier loop (`references/11-maker-verifier-loop.md`) with a checksum safety net.
9. **Offer a chat-app (LINE) face only as a progressive, opt-in step — never pitch it up front.** The gate has three parts, in order: (a) **first confirm the KB is actually live on NotebookLM and answering correctly** (the QA loop passed — a bot on a hallucinating KB just distributes the hallucination faster); (b) **then ask the user** whether they want to put it on a chat app such as LINE; (c) **only if the user says yes, load `references/12-notebooklm-line-bot.md`** and proceed. Do not push reference 12, the bot, or the template before asking — surfacing it unsolicited is a violation of this gate.

## Reusable artifacts in this template
- `scripts/make_nlm_upload.py` — converts SSOT Markdown's fenced code blocks to plain-text-marked form so the Q&A tool can index SQL/commands verbatim. (Critical: see gotchas.)
- `references/03-qa-and-audit.md` — the QA grading rubric (✅/⚠️/❌) and the four-layer integrity audit.
- `references/04-monthly-update-sop.md` — the repeatable monthly refresh + CI-style coverage diff.
- `examples/` — a fully fictional before/after showing scattered, contradictory docs consolidated into a sourced SSOT.
- `templates/line-bot-service/` — a de-identified, deployable LINE-bot service (FastAPI + the `notebooklm` CLI) that gives your KB a chat-app face. Ship only after the progressive gate above; see `references/12-notebooklm-line-bot.md`.

## Methodology sources (index)
- Anthropic — *Contextual Retrieval*: prepend per-chunk context/source to cut retrieval failures (~35% in Anthropic's tests). Basis for the per-section source tags. — https://www.anthropic.com/news/contextual-retrieval
- Anthropic — *Agent Skills best practices*: progressive disclosure (lean `SKILL.md` router + `references/` loaded on demand, avoid deep nesting). Basis for this template's structure. — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- RAG chunking practice: Markdown is the most LLM-native format; heading-aware splitting beats fixed-length; extractive beats abstractive for lower hallucination.