proof-kb

name: proof-kbdescription: Build and maintain an atomic First-Hand Proof Knowledge Base (seo/kb/) inside a repository, draft or upgrade pages with Consensus + Proof Card architecture, and propagate new benchmarks or facts across every matching page via route-fact. Use when scaffolding seo/kb/, extracting founder proof from transcripts or interviews, upgrading thin SEO posts with real receipts, or routing a new benchmark, customer win, or pricing change across multiple pages.metadata:   author: illyism  source: https://il.ly/skills/proof-kb  version: 1.0.0

First-hand proof knowledge base (seo/kb/)

FAQ schema, fresh updatedAt dates, author bios, and word counts no longer separate ranking pages from AI-generated commodity posts, because every competitor copies them in seconds. Pages that hold top-3 Google positions and get cited by ChatGPT, Claude, and Perplexity do two things a competitor cannot copy:

1. Open with a concrete first-hand receipt in the first 2 sentences (an exact test count, latency delta, dollar figure, or production dataset).
2. Stack at least 4 of the 5 proof categories below across the body.

Store every verifiable fact once in seo/kb/ and wire those atomic proof files into money pages, comparisons, and blog posts. Agents writing from one fact store stop inventing specs and quoting stale prices.

Workflow routing decision tree

Walk this tree on every invocation:

Does `seo/kb/brand-ssot.md` exist?
├── No -> Workflow 1: `init`, then continue down this tree
└── Yes
    ├── Did the user just ship a benchmark, customer win, pricing change, or release?
    │   └── Yes -> Workflow 4: `route-fact`
    ├── Does the user want a site-wide proof gap audit?
    │   └── Yes -> Workflow 2: `interview` across the top 5 money/blog pages in `seo/kb/pages-index.md`
    └── Is the user drafting or upgrading a specific page?
        ├── Fewer than 4 proof categories in `seo/kb/proof/` match this page's topic?
        │   └── Yes -> Workflow 2: `interview`, then Workflow 3
        └── 4 or more -> Workflow 3: `draft` / `upgrade`

The 5 categories of first-hand proof

Every commercial guide, comparison page, or benchmark post ships with at least 4 of these 5 categories. One claim type repeated five times still reads as thin marketing copy to buyers and retrieval models.

Workflow 1: init (scaffold seo/kb/)

Read package.json, pricing config, database schemas, and the existing /pricing, /about, and /blog sources, plus every raw proof source in the repo: benchmark results (bench/, benchmarks/), analytics or warehouse exports and case-study data (data/), and incident postmortems (docs/runbooks/, postmortems/). Then create these four files. Each proof file names its raw source in a source: frontmatter field, so a reviewer can check the number in 1 click.

1. seo/kb/brand-ssot.md (single source of truth)

Exact product mechanics, pricing tiers, supported stack, and what the product does NOT do. Write only facts you found in the codebase or that the user confirmed; mark anything else [UNVERIFIED].

# Brand SSOT: QueryBench (querybench.dev)
Last verified: 2026-11-12

## Product mechanics
- Runs Postgres and MySQL query regression benchmarks on every GitHub pull request.
- Spins up an ephemeral copy-on-write database branch in `1.8s` using ZFS snapshots.
- Parses `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` and fails the CI check if p95 execution time regresses by `> 15%` or buffer reads rise by `> 20%`.

## Pricing tiers
- Free: `$0/month` for 3 repositories and 100 PR benchmark runs/month.
- Pro: `$49/month` flat for unlimited repositories, 2,500 PR runs/month, 90-day flamegraph retention.
- Team: `$199/month` flat (no per-seat pricing) with SOC 2 reports, Slack alerts, and custom ZFS runners.

## Boundaries (what we do NOT do)
- No Oracle or Microsoft SQL Server (Postgres 14-17 and MySQL 8.0+ only).
- No persistent daemon inside production RDS instances.

2. seo/kb/proof/{benchmarks,customers,numbers,workflows}/<id>.md

One file per verifiable fact or test. One file per fact lets several pages cite the same number and lets route-fact update every dependent page in one pass when the test is re-run.

---
id: bench-zfs-branch-spinup-2026
category: benchmarks
date: 2026-11-04
topics: [postgres-branching, ci-database-testing, explain-analyze]
verified: true
source: bench/results/zfs-branch-spinup-2026-11.json
---

# 50GB Postgres branch spin-up: ZFS copy-on-write vs pg_dump restore

## Methodology
- Dataset: `50.4 GB` production-shaped Postgres 16 database (`180M` rows, 42 tables).
- Hardware: AWS `i4i.xlarge` (`4 vCPU`, `32 GB RAM`, NVMe), 50 consecutive cold runs.

## Raw numbers
| Method | Median | p99 | Disk per branch |
| --- | --- | --- | --- |
| `pg_dump` + `pg_restore -j 4` | `14m 22s` | `18m 05s` | `50.4 GB` |
| EBS snapshot clone | `48.6s` | `74.1s` | `50.4 GB` (provisioned) |
| QueryBench ZFS clone | `1.8s` | `2.4s` | `12 MB` delta on creation |

## Failure note
Pin ZFS ARC to at least `50%` of RAM (`zfs_arc_max`). Inside Docker with tight cgroup memory limits, the first sequential scan benchmark runs `3.2x` slower.

## Reusable snippet
In our 50-run benchmark on a `50.4 GB` Postgres 16 dataset (`180M` rows on `i4i.xlarge`), `pg_restore -j 4` took a median of `14m 22s` per PR environment, while a ZFS copy-on-write clone booted in `1.8s` (`2.4s` p99) using `12 MB` of disk.

3. seo/kb/competitors/claims-to-beat.md

The exact numbers ranking competitors cite, each paired with the larger test that beats it. This turns a SERP review into an engineering task list. No SERP or Ahrefs access in this session: fill the "Our stronger test" column from seo/kb/proof/, write [NEEDS SERP] in the competitor columns, and leave the file in place for the next run (dataforseo-serp Workflow D fills them). Why: an invented competitor claim is a fabricated statistic about someone else.

# Competitor claims to beat

| Keyword | Competitor URL | Their claim | Our stronger test | Status |
| --- | --- | --- | --- | --- |
| `postgres ci testing` | `competitor-a.com/blog/ci-db` | 3 Docker setups on a `100 MB` toy DB | 50 runs on a `50.4 GB` DB comparing `pg_restore`, EBS, ZFS (`bench-zfs-branch-spinup-2026`) | Shipped |
| `explain analyze tool` | `competitor-b.io/guides/explain` | 2 static `Seq Scan` examples | 10 real production regressions with before/after index buffer counts | Open |

4. seo/kb/pages-index.md

Every commercial page and post mapped to its keyword and proof IDs. route-fact reads this file to find which pages a new fact touches.

# Proof-to-page index

| File path | URL | Primary keyword | Proof IDs | Categories |
| --- | --- | --- | --- | --- |
| `content/blog/postgres-ci-testing.mdx` | `/blog/postgres-ci-testing` | `postgres ci testing` | `bench-zfs-branch-spinup-2026`, `cust-invoicekit-ci-cut`, `num-q3-regression-causes`, `wf-zfs-arc-limit` | 4/5 |
| `app/pricing/page.tsx` | `/pricing` | `querybench pricing` | `brand-ssot`, `cust-invoicekit-ci-cut` | 2/5 |

Workflow 2: interview (fill proof gaps, never invent)

Never invent benchmarks, customer quotes, latency numbers, or incidents. One fabricated "we tested 50 tools" claim that a reader disproves costs the whole domain its trust, and fake customer outcomes create legal exposure.

Run this when a page has fewer than 4 proof categories or leans on generic claims ("many teams struggle with slow CI").

Step 1: Mine existing recordings with Scribiz

If the user has founder voice notes, YouTube demos, sales calls, or audit videos, connect Scribiz (MCP: https://scribiz.com/mcp, or npx scribiz). Call get_video_context first for chapters and key moments, then search_video for the exact phrase, because pulling a full 2-hour transcript burns 25,000+ tokens. Save each verified number or story as an atomic file in seo/kb/proof/ before touching the article.

Step 2: Ask 3-5 bounded founder questions

If recordings are missing or leave gaps, ask exactly 3 to 5 questions that each produce one number or one edge case:

To make `/blog/postgres-ci-testing` rank and get cited without inventing data, I need 3 facts:
1. **Metric:** What is the real median boot time and database size for your CI branches today?
2. **Customer win:** One customer (or an anonymized profile like "a 12-person Series A fintech") and their exact before/after metric.
3. **Failure note:** One non-obvious config mistake that broke when you ran this in production.

Save answers as atomic files and update seo/kb/pages-index.md before writing prose.

If the user cannot answer now, write the questions to seo/kb/open-questions.md and put [NEEDS PROOF: <question>] markers in the draft where each fact belongs. A visible gap gets filled; an invented number ships.

Workflow 3: draft / upgrade (Consensus + Proof Card architecture)

Build every <h2> section from two layers:

1. [CONSENSUS]: the definitions, syntax, and subtopics that 4 or more of the top 5 ranking pages cover. Cover them in as few words as possible, because missing them signals an incomplete page while repeating them adds nothing.
2. [PROOF]: one or more atomic files from seo/kb/proof/ (plus a real screenshot or deterministic chart) that no competitor has.

Outline blueprint (write before prose)

Save it to seo/kb/outlines/<slug>.md. The [CONSENSUS] and [PROOF] tags live in the outline only; the published page carries the prose and numbers, never the tags. Without SERP access, tag consensus lines [CONSENSUS] [NEEDS SERP] so the next run checks them against the real top 5.

## H2: How ephemeral database branching works in CI
- [CONSENSUS]: copy-on-write blocks vs full file copies; the 6-line GitHub Actions YAML.
- [PROOF -> `bench-zfs-branch-spinup-2026`]: 50.4 GB / 180M-row table (`1.8s` ZFS vs `14m 22s` `pg_restore`).
- [PROOF -> `wf-zfs-arc-limit`]: the `zfs_arc_max` cgroup memory trap and the fix.

Execution rules

1. Write the introduction last. Draft every body section first, then open with the single sharpest [PROOF] receipt in the first 2 sentences. You only know your strongest number after assembling the body, and readers and retrieval systems judge authority in the first 40 words.
   • Bad: "In modern software development, testing database migrations in CI has become increasingly important for engineering teams."
   • Good: "Restoring a 50.4 GB Postgres dump in GitHub Actions takes a median of 14 minutes and 22 seconds. A ZFS copy-on-write branch boots the same 180-million-row dataset in 1.8 seconds. Below: the benchmark across 50 cold runs, the Docker memory trap that slows scans by 3.2x, and how to wire sub-2-second branching into your PR pipeline."
2. Count proof categories. If the finished draft has fewer than 4 of 5, go back to Workflow 2. Do not ship at 3.
3. Register the page. Add or update its row in seo/kb/pages-index.md so future facts route to it.

Workflow 4: route-fact (multi-page propagation)

When a new benchmark, case study, price, or release lands, push it to every page that depends on it in one change:

1. Write the source file: seo/kb/proof/<category>/<new-id>.md, or edit seo/kb/brand-ssot.md for pricing and feature changes. A re-run of an existing test gets a new dated ID (bench-zfs-branch-spinup-2026-12) with supersedes: <old-id> in its frontmatter; add superseded_by: <new-id> to the old file and keep it. Why: the old number stays citable as history ("down from 1.8s in November") and the diff shows exactly which test moved. If a release caused the change, update the mechanism line in brand-ssot.md too.

2. Find dependents: read seo/kb/pages-index.md, then grep the repo for the topic tags, the superseded proof ID, and the old number itself (pages added outside the index still quote it):

   grep -rnF --exclude-dir={node_modules,.next,.git,dist,build} -e '1.8s' -e '1.8 s' -e 'bench-zfs-branch-spinup-2026' .
   

   Use -F and exclude build output. Why: an unescaped 1.8s regex also matches 1x8s, and node_modules plus .next bury the real hits under dozens of false ones. Open every hit and confirm it is the same metric on the same workload. The same number can measure something else (a page's 1.8s LCP is not a 1.8s branch spin-up): skip it and note it in that page's pages-index.md row so the next run skips it too. Raw result files under bench/ stay untouched.

3. Edit every match in place:

   • Replace the stale number or generic paragraph with a snippet backed by <new-id>, rewritten for that page's context.
   • Never paste the same sentence into more than one URL; identical boilerplate across pages reads as templated.
   • Bump updatedAt / lastModified only on pages where a fact changed.

4. Update seo/kb/pages-index.md with <new-id> against every touched file, and swap the old ID in seo/kb/outlines/ and seo/kb/competitors/claims-to-beat.md.

Example summary

NEW PROOF: seo/kb/proof/customers/cust-invoicekit-ci-cut.md
Matched 3 pages:
├── content/blog/postgres-ci-testing.mdx (42,000-webhook migration outcome under H2 #3)
├── app/vs/branchbase/page.tsx (compute spend row: $1,840 -> $290/mo)
└── app/pricing/page.tsx (ROI callout above the Pro tier card)

Measuring citation lift

After shipping proof-backed pages or a route-fact pass, add the target buyer prompts to AI SEO Tracker (MCP: https://aiseotracker.com/api/agent/mcp). It shows when ChatGPT, Perplexity, Claude, Gemini, and Google AI Overviews start citing the new numbers, so you know which proof moved the needle.

Verification checklist

• seo/kb/brand-ssot.md and seo/kb/pages-index.md exist and reflect this run's edits.
• Every number or customer outcome on touched pages traces to seo/kb/proof/ or seo/kb/brand-ssot.md, or carries a [NEEDS PROOF] marker listed in seo/kb/open-questions.md.
• Touched articles open with a first-hand receipt in the first 2 sentences.
• Touched long-form pages stack 4 or more proof categories.
• Zero fabricated statistics and zero em dashes in created or edited files. An upgraded page that still carries legacy prose goes through the unslop-seo pass and its check script next. Why: proof-kb adds receipts; it does not clean the old paragraphs around them.