knowledge-base-builder

Purpose

Your projects are documented in your head, in a hundred calls, and in threads nobody will read again. This skill turns that into a documentation pack that makes every future AI session productive, which is the actual payoff. A well-built knowledge base means the next agent does not need the meeting.

It ingests one project's meetings, message threads, on-screen artifacts, and documents from Littlebird capture, and writes a structured markdown pack: product requirements, architecture notes, decision records in a recognized format, a glossary, a brand brief where the project has positioning, an open questions register, and a contradiction register.

The contradiction register is the part that makes the rest trustworthy. Real projects contain conflicting statements over time: a number quoted two ways in two calls, an approach agreed and silently reversed, figures that do not match across sources. A skill that quietly picks one produces documentation that is confidently wrong, and the evidence says the model reading it will not notice. Given two passages containing contradictory facts, all models tested in the WikiContradict benchmark struggled to produce answers reflecting the conflict, and under a prompt that explicitly told them to look for contradictions the best correct rate was 43.8 percent [references/research/distilled-documentation-architecture.md section 5]. So this skill surfaces every conflict with both readings, both dates, and both receipts, and asks you to resolve it.

Mode: on-demand per project, with an optional monthly refresh routine that watches for staleness and hands back.

---

Littlebird MCP calls used

Real tool names, verified 2026-08-17. List the tools available in your session before calling anything; these are a starting point, not a contract.

Tool	Used for
LB_INTERNAL_LIST_MEETINGS	The project's recurring calls, by name. Also upcoming events, with a future end_date.
LB_INTERNAL_SEARCH_MEETINGS	The topic sweep across meetings, by query
LB_INTERNAL_GET_MEETING	The structured Decisions, Action Items, and Risks blocks, which are the spine of the pack
LB_INTERNAL_GET_MEETING_TRANSCRIPT	Verbatim wording for a decision record quote, selectively
search_user_context with data_source: snapshots	On-screen artifacts: designs, schemas, dashboards, docs
search_user_context with data_source: messages	Thread-level decisions that never reached a call
LB_INTERNAL_LIST_ROUTINES	Check for an existing refresh routine before offering to create one
LB_INTERNAL_GET_ROUTINE_CONFIG	Read a routine's current prompt before updating it
LB_INTERNAL_GET_ROUTINE_REPORTS	Read what the refresh routine has already flagged
LB_INTERNAL_CREATE_ROUTINE	Create the refresh routine, after approval
LB_INTERNAL_UPDATE_ROUTINE	Change an existing refresh routine
LB_INTERNAL_GET_SUBSCRIPTION_STATUS	Check the plan gate and the routine limit

A meeting lookup by NAME uses the list tool with name. A lookup by TOPIC uses the search tool with query. Using the wrong one is the most common retrieval mistake against this server (references/littlebird-mcp-reference.md, retrieval pattern 6).

---

Trigger

"Build a knowledge base for PROJECT", "document this project", "write the PRD from my calls", "what did we decide on PROJECT and when", "make a docs pack I can feed to Claude", "get this project out of my head", "write architecture notes for PROJECT", "I need to brief a contractor on PROJECT", "refresh the PROJECT knowledge base".

Not for writing a new specification for something that has not been discussed yet. This skill documents what exists in capture. With no capture there is nothing to document, and it stops.

---

Routine cadence

On demand per project. The pack is built in an interactive session because every material fact passes a confirmation gate and a routine cannot run gates.

Optional monthly refresh routine. It observes only: it detects that the project has moved on since the pack was built, names which documents are stale, and hands back to a Cowork session. Exact prompt text in the routine wiring section below.

---

Capability gate

This skill requires the Littlebird MCP on a Power or Pro plan.

1. List the tools actually available in this session and use the real names you find. Do not assume the names in references/littlebird-mcp-reference.md are still exact. That file is verified as of 2026-08-17 and is a starting point.
2. If no Littlebird tools are present, stop. Tell the user this skill needs the Littlebird MCP connected, and that it cannot build a knowledge base from a description of the project.
3. If the plan gate is in doubt, call LB_INTERNAL_GET_SUBSCRIPTION_STATUS before promising a pack. Check it again before offering the refresh routine, because routine count is plan-limited.

There is no degraded mode. A pack written without capture is fiction, and it is fiction that will be loaded into every future session about this project.

---

Do this first, every time

Read these two, in this order, before touching retrieval:

1. references/evidence-standards.md for the receipt format, the observed / inferred / external / unknown split, the attribution guardrail, and the confirmation gates.
2. references/littlebird-mcp-reference.md for tool parameters, return shapes, and the limitations to design around.

Then read references/project-scoping.md and follow it. The other four guides load at the stage that needs them.

---

Process

Seven stages. Stage 4 runs before stage 5, and stage 5 before stage 6, and neither ordering is negotiable.

Stage	Guide	Output
1. Scope the project	references/project-scoping.md part 1	Confirmed boundary: names, calls, people, window, purpose
2. Sweep	references/project-scoping.md part 2	Raw retrieval across seven sweeps
3. Sort, deduplicate, score	references/project-scoping.md part 3	A time-ordered, deduplicated fact ledger
4. Contradiction pass	references/contradiction-register.md	The register, with both readings on every conflict
5. Sensitive segregation	references/sensitive-segregation.md	Three-way sort: main pack, segregated file, dropped
6. Confirm	references/evidence-standards.md rule 6, plus the two gates below	Corrected ledger, resolved conflicts, approved segregation
7. Write the pack	references/pack-structure-and-formats.md and references/ai-ingestible-structure.md	The files

Stage 1: scope

Ask four things with AskUserQuestion: what the project is called and what else it has been called, which recurring calls belong to it, who is on it, and what window. Also ask what the pack is for, because a pack for a contractor and a pack for the user's own AI sessions differ in what gets segregated. Read the boundary back before sweeping.

Stage 2: sweep

Seven sweeps, specified with their exact queries in references/project-scoping.md part 2. Windowed, narrow, parallel: five specific queries beat one vague query and avoid the oversized-result file dump (references/littlebird-mcp-reference.md, retrieval patterns 1 and 2).

A. Recurring call spine, LB_INTERNAL_LIST_MEETINGS with name, one call per recurring call. B. Topic sweep, LB_INTERNAL_SEARCH_MEETINGS, six parallel queries including "PROJECT what we agreed to change", which is how reversals surface. C. Structured blocks, LB_INTERNAL_GET_MEETING per id. The ## Decisions, ## Action Items, and ## Risks / Open Questions blocks are the spine of the decision records and the open questions register, and they already carry owner attribution (references/littlebird-mcp-reference.md, "What a meeting summary already contains"). D. Transcript, LB_INTERNAL_GET_MEETING_TRANSCRIPT, only for decisions you intend to record, only for wording and reasoning, never to establish who said something. E. On-screen artifacts, search_user_context with data_source: snapshots, month by month, six queries covering designs, schemas, diagrams, dashboards, specs, roadmaps. Snapshots are the primary source for the data model. F. Thread decisions, search_user_context with data_source: messages, six queries. This is where the decisions that never reached a call live. G. Vocabulary, targeted queries per candidate term, across both sources.

Stage 3: sort, deduplicate, score

Sort by event time, because retrieval is relevance-ordered (references/evidence-standards.md rule 8). Deduplicate, because OCR of dense UI produces repeated lines and repetition is not corroboration (references/littlebird-mcp-reference.md, known limitations). Read the relevance scores; anything scored 3 is a maybe (retrieval pattern 5).

Build the fact ledger described in references/contradiction-register.md, with a separate Value column. A conflict between two sentences is hard to see. A conflict between two values in one column is trivial to see.

Stage 4: the contradiction pass

A named stage with its own retrieval, its own file, and its own gate. Full procedure in references/contradiction-register.md. Six kinds to sweep for: numeric, reversal, definitional, scope, attribution, temporal. Then the reversal sweep, which searches forward from each recorded decision for evidence the project is doing something else, because a reversal has only one recorded statement and the other side is an absence.

Recency wins by default and never silently. The later statement is the working answer and is what the pack encodes. The earlier one is retained in the register with its date and its receipt, and the entry says which was used and why. Where the earlier statement is High confidence and the later one is Low, recency does not win automatically; that goes to the user unresolved.

This mirrors how decision records already handle a reversal: the old record is not edited or deleted, it is marked superseded with the replacement's number so the chain is traversable forward [references/research/distilled-documentation-architecture.md section 2]. Extending that model to non-decision facts is this skill's own design decision and no source in the archive does it [references/research/distilled-documentation-architecture.md section 9].

Stage 5: sensitive segregation

Before any file is written, not as a review at the end. Full procedure in references/sensitive-segregation.md. Five categories: financial, equity and ownership, legal, personnel, third-party confidential. Three-way sort: main pack, segregated file, or dropped. Four detection sweeps, including the screen-share sweep, which is the one that surfaces another company's numbers sitting in the user's capture.

Stage 6: confirm before you encode

Two gates, both with AskUserQuestion, in this order.

Gate A, the contradiction resolution gate. One question per conflict, both readings shown with their dates and receipts, three options every time: reading A, reading B, or both are wrong. Never present a default as pre-selected. "I do not know" is a legitimate answer and the entry stays unresolved. This gate runs first because the answers change what the other documents say.

Gate B, the encoding gate. Anything written down as durable fact about a person, a company, a commitment, or a number gets confirmed first (references/evidence-standards.md rule 6). Batch by document rather than asking about every line. Confirm: every Low and Medium confidence fact, every inferred line, every glossary definition, every non-goal, the data model coverage claim, and the segregation assignments.

A knowledge base is durable and will be fed to future agents, so an unconfirmed fact in it propagates into work the user never watches happen. That is why this gate is heavier here than in a skill that produces a one-off report.

Stage 7: write

references/pack-structure-and-formats.md for what each file contains and which decision record format to use. references/ai-ingestible-structure.md for the writing rules and for which of them are actually evidenced.

Then delete the working ledger and the raw retrieval. Raw capture never ships (references/evidence-standards.md rule 7).

---

Output

One directory, knowledge-base/PROJECT-SLUG/, written to the working directory.

File	Contents
00-index.md	What the project is, a table of every file with a one-line description, the provenance block, the omissions list, counts of open questions and unresolved contradictions and segregated items, and the confirmation record
01-glossary.md	One entry per project term, alphabetical: canonical form, observed variants, one-sentence definition, first use with receipt, confidence
02-product-requirements.md	Problem and outcome, users and use cases, goals, non-goals, functional requirements, acceptance criteria in Given / When / Then form, non-functional requirements, dependencies, open questions, sources. Split per feature as 02-prd-FEATURE-SLUG.md where the project has more than about three
03-architecture.md	System overview as one relationship per line, plus the data model as far as capture supports, with coverage marked as fully observed, partial, or named only
04-decisions/NNNN-kebab-case-title.md	One record per decision, format chosen by what the capture supports: MADR where options were argued, Nygard where forces are visible, Y-statement where only the tradeoff is. Plus index.md listing number, title, status, date
05-brand-brief.md	The five positioning components in order, with empty components marked empty rather than filled in. Only where the project has positioning material
06-open-questions.md	Table: question, why it matters, source, date raised, status
07-contradictions.md	One entry per conflict: kind, status, reading A and reading B each with value, date, receipt, quote and confidence, what the pack currently says, and which files change if the resolution flips. Ships even when empty
SENSITIVE-PROJECT-SLUG.md	Segregated items with category, fact, why it was kept, receipt, confidence. Uppercase prefix so it sorts to the top and cannot be missed. Only where segregated material exists

Omit a document rather than pad it, and record every omission in the index. A pack with four documents and a stated absence beats six documents where two are speculation.

---

Evidence standards

Apply references/evidence-standards.md in full. The five that bite hardest here:

• Every material fact carries a receipt (rule 1). Meeting form [Meeting name, 2026-08-03, Decisions]. Message form carries both the collection time and the send time, because they are different values and both matter.
• Observed, inferred, external, and unknown are visibly different (rule 2). In this pack: observed lines carry a receipt, inferred lines begin with "Inferred:" and name what they rest on, external lines carry a URL, and unknown items go to the open questions file rather than becoming a hedged sentence in place.
• Attribution guardrail (rule 4). Capture shows what was on screen, not what the user wrote, and raw transcript chunks are weakly diarized and frequently tagged [Others]. Take who-decided from the meeting summary's ## Decisions block. Quote transcript for wording only.
• Partial rosters are reported as partial (rule 5). This generalizes here to the data model: a partially captured schema presented as complete is the same defect. Mark coverage.
• Confirm before you encode (rule 6). Heavier here than elsewhere, because the artifact is durable and gets fed to future agents.

The rule this skill adds: a requirement without a receipt is not a requirement, it is an open question. The same goes for a data model field, a non-goal, and a positioning claim.

---

Empty retrieval

Situation	Action
No Littlebird tools in session	Stop at the capability gate.
No recorded meetings for any named recurring call	Report it. Those calls may be unrecorded calendar entries, which carry no id, no summary, and no transcript. Ask whether the project lives in threads and screens instead. If so run sweeps E and F only and state in the pack that the meeting spine is absent.
Meetings empty, snapshots and messages productive	Buildable, with no attributed decision records. Say so before writing. A decision taken from a snapshot alone is an inference and is marked as one.
Fewer than roughly 3 recorded meetings and roughly 20 distinct snapshots after dedup	Too thin for a pack. Report what was found, name it a fragment, and offer a single project-context note instead of six documents. Do not pad.
One artifact type has nothing	Omit that document and name the omission in the index. An empty architecture note is worse than a stated absence.
Everything scored 3	Report low confidence across the pack and widen gate B to cover material you would otherwise have passed.

A failed or empty retrieval ends the run (references/evidence-standards.md rule 9). A skill that reports "I found nothing for this window" is doing its job correctly.

---

Routine wiring: the monthly staleness watch

The on-demand run is the primary mode. The routine is a cheap observer that notices the project has moved on and hands back. It cannot rebuild the pack, because rebuilding requires the two confirmation gates and a routine cannot run gates (references/littlebird-mcp-reference.md, "Do not ask a routine to do work it cannot finish unattended in one pass").

Offer to create it. Routines can be created from an interactive session; only a running routine is blocked from creating them (references/littlebird-mcp-reference.md, Routine tools). Show the user the exact prompt text and schedule below, get approval with AskUserQuestion, then call LB_INTERNAL_CREATE_ROUTINE. Do not tell the user to go set it up by hand.

Call LB_INTERNAL_LIST_ROUTINES first. If a watch already exists for this project, do not create a second one. Call LB_INTERNAL_GET_ROUTINE_CONFIG and offer an update instead, remembering that prompt and schedule each replace the whole field.

Title: Knowledge base staleness watch: PROJECT NAME

Schedule: {"frequency": "monthly", "month_day": 1, "time": "08:00"}

Monthly is this skill's convention and is not a measured optimum. The nearest anchor in the research is the quarterly architecture review of a decision record collection [references/research/distilled-documentation-architecture.md section 9]. Monthly is chosen because a small project moves faster than an enterprise architecture, and the user can change it.

Notifications: push on. Email if the user wants a copy.

Prompt text, verbatim:

You are a monthly staleness watch for a project knowledge base. Your job is to notice that
the project has moved on since the knowledge base was written, and to name which documents
are now stale. You do not rewrite anything, you do not resolve anything, and you do not draft
any document. You observe and you report.

The project is: PROJECT NAME
Its recurring calls are: LIST THE CALL NAMES
The knowledge base was last built on: YYYY-MM-DD
The documents in it are: 00-index, 01-glossary, 02-product-requirements, 03-architecture,
04-decisions, 05-brand-brief, 06-open-questions, 07-contradictions

FIRST, before searching, call LB_INTERNAL_GET_ROUTINE_REPORTS for this routine with limit 6
and read your own previous reports. You need them to tell a new signal from one you have
already flagged, and to escalate correctly. Do not skip this step.

Then run four retrievals, each windowed to the period since your last report, or since the
knowledge base build date if this is your first run.

RETRIEVAL 1. Call LB_INTERNAL_LIST_MEETINGS with the name of each recurring call listed
above, and a start date at the beginning of your window. Count how many project meetings
happened. A meeting lookup by name uses the list tool with name. Do not use the search tool
for this.

RETRIEVAL 2. Call LB_INTERNAL_SEARCH_MEETINGS with a start date at the beginning of your
window, once per query, for these queries with the project name substituted in:
"PROJECT decision on approach", "PROJECT what we agreed to change", "PROJECT requirements and
scope", "PROJECT architecture and data model". For each meeting that comes back, call
LB_INTERNAL_GET_MEETING and read its Decisions block and its Risks and Open Questions block.
Those two blocks are the signal. Do not pull transcripts.

RETRIEVAL 3. Search the user's captured context with data_source set to snapshots, windowed
to the period, using several narrow queries rather than one broad one: "PROJECT design mockup
or wireframe", "PROJECT database schema or table structure", "PROJECT architecture diagram",
"PROJECT specification document". You are looking for artifacts that did not exist when the
knowledge base was built.

RETRIEVAL 4. Search the user's captured context with data_source set to messages, windowed to
the period, for: "PROJECT changed my mind about", "PROJECT let us go with this approach",
"PROJECT we are cutting", "PROJECT what do we call this". Thread decisions are the ones the
knowledge base is most likely to have missed.

Write a report with exactly these five sections.

STALE DOCUMENTS
For each of the eight knowledge base documents, one line: the document name, and either
"current" or "stale" with the reason in under fifteen words and the receipt in the form
[Weekday, Month D, YYYY HH:MM TZ | app] or [Meeting name, YYYY-MM-DD, Decisions]. Rank the
stale ones first. The strongest staleness signal is a decision or artifact that exists now and
was never written down at all, so weight new material above changed material.

NEW DECISIONS
Every decision found in a Decisions block inside your window, with who decided, the date, and
the receipt. If a decision appears to reverse something the knowledge base records, say so
plainly and put it first in this section. Do not resolve it. Do not decide which is correct.
Say that both readings exist and that resolving it needs a Cowork session.

NEW TERMS
Any project-specific word, acronym, or product name that appears in your window's material.
List the term and one receipt each. Do not define them, you do not have enough context to
define them correctly. The glossary is built with the user, not by you.

POSSIBLE CONTRADICTIONS
Anything in your window that disagrees with anything else in your window, or that disagrees
with something you flagged in a previous report. Give both values, both dates, and both
receipts. Give no opinion on which is right. If you find none, write "none detected in this
window" rather than leaving the section out.

WHAT TO DO
One line naming the Cowork skill and the scope. Use exactly this shape: "Open Cowork and run
knowledge-base-builder for PROJECT NAME, scoped to WINDOW, to refresh: LIST THE STALE
DOCUMENTS." If nothing is stale, write "No refresh needed this month" and stop.