--- name: synthesis-knowledge-capture description: Capture durable session facts in an OKF knowledge base with corpus-wide deduplication, confidentiality routing, conflict reconciliation, provenance, validation, and repository-aware shipping through synthesis-kb-edit. Use at session end, when asked to capture or update knowledge, merge facts into ai-knowledge, or preserve corrected facts about people, organizations, products, decisions, or strategy. license: CC0-1.0 depends_on: - synthesis-okf - synthesis-kb-edit metadata: author: Rajiv Pant version: "1.1.0" source_repo: "github.com/synthesisengineering/synthesis-skills" source_type: "public" --- # Knowledge Capture **Version 1.1.0** (2026-07-29) A fact learned in a session and not written to the durable knowledge base is a fact lost. This skill is the disciplined path from "the agent now knows X" to "the knowledge base now knows X" — without duplicating, without overwriting a still-true fact, and without leaking a confidential fact into a shared corpus. ## Why it exists Most knowledge bases have a rule like *"update `source/` when you learn something."* A rule is not a workflow, and a manual rule drifts. The failure has three shapes, all real: - **Evaporation.** The corrected fact lives only in the session transcript. The next session starts blind and repeats the old mistake. - **Duplication.** A naive append adds a second, contradictory concept. Now the corpus asserts two things and a reader cannot tell which is current. - **Destruction.** A blind overwrite deletes a framing that was still accurate on a different axis, replacing signal with a plausible error. The canonical trigger: an agent learns a corrected fact about a person's role. The corpus already holds several references to that person under a prior framing. Evaporation loses the correction; duplication contradicts; a blind flip destroys references that were right all along. The only safe path is: find every existing mention first, decide in place, reconcile rather than flip, cite the source. That path is this skill. ## The configuration contract All routing specifics live in a PRIVATE config the skill reads at load time: ``` ~/.synthesis/knowledge-capture/config.json ``` It maps knowledge **domains** to a target repo, a confidentiality **tier**, and the OKF bundle path inside that repo; it names the **confidential terms** that must never reach a public repo; and it records each repo's **push posture** (auto, or hold-for-approval). This skill is generic and publishable; the config is neither. If the config is missing, STOP and say so — routing a fact without the routing table is guessing, and guessing about confidentiality is how a private fact ends up in a shared corpus. Each target repository must also carry `.agents/knowledge-base.yaml`. The private capture config answers **which repository receives the fact**; the repository contract answers **what may be edited there, which schema applies, and how the change ships**. Stop if either layer is missing or they disagree on the bundle path. ## The capture workflow Run these in order. Never skip step 3. 1. **Extract.** From the session, list the *durable* facts — things true beyond this conversation: people, roles, reporting lines, product ownership, decisions and their rationale, stable technical facts. Exclude the ephemeral (today's task state, one-off logistics). State each as one atomic claim with its in-session source (who said it, which tool call surfaced it). 2. **Route.** For each fact, choose the target from config by confidentiality tier (see Confidentiality routing). One fact may split: the neutral fact to a shared KB, the candid framing to a private one. 3. **Scan before writing.** Run `kb_scan.py` for every entity the fact touches, across the target bundle. This returns *every* file and line that already mentions the entity. You cannot merge in place without first knowing every place the entity already lives. This step is mandatory; skipping it is how duplication and destruction happen. 4. **Merge in place.** Update the concept that owns the fact (a person's directory entry, a product's page). Do not append a new dated note to a reference concept — reference tiers are updated in place. If the fact is genuinely new (a departure, a new hire), add it to the concept that already holds that class of fact (the departures table, the roster). 5. **Validate.** Run both `synthesis-okf` layers: OKF conformance on the bundle and configured metadata consistency on every touched concept. Resolve all conformance errors, conflicts, and duplicates before shipping. 6. **Log provenance.** Append a `log.md` entry (`## YYYY-MM-DD`, newest first) naming what changed and the in-session source. `log.md` is OKF-reserved and excluded from compiled knowledge; it is the audit trail, not content. 7. **Ship through `synthesis-kb-edit`.** Hand the exact touched-file list and validation results to the configured editor workflow. It rechecks editable, refused, generated, confidentiality, branch, host, and review policy before staging or publishing anything. ## Merge discipline — the four hard rules 1. **Scan first, always.** No write without a completed `kb_scan.py` for every entity involved. The scan is the difference between merging and littering. 2. **In place, not append.** Stable facts are corrected where they live. A new concept file is for a genuinely new unit of knowledge, not for a fact that updates an existing one. 3. **Reconcile, never blind-flip.** When a new fact contradicts the corpus, the contradiction is data, not a mandate to overwrite. See below. 4. **No fact without a source.** Every merged claim cites its in-session origin. If you cannot name who said it or which tool surfaced it, you cannot write it — the same provenance bar the rest of the synthesis stack enforces. ## Confidentiality routing - **Default to the most private tier that fits.** When unsure whether a fact belongs in a shared corpus, it does not. Route it private and flag the question. - **Split neutral from candid.** Org-structure facts (title, reporting line, who owns a product) are usually fine for a shared internal KB. Candid framing (why someone left, a performance read, negotiation posture) is not — that is private, always, regardless of how the fact was learned. - **A public repo takes no confidential term.** If the target is a public repo, the config's confidential-term list is a hard filter: any fact containing one is rerouted to a private target or dropped, never sanitized-and-shipped. - **Learned-in-a-shared-channel is not permission.** Where a fact was surfaced does not set where it may be stored. The confidentiality tier of the *fact* governs, per config. ## Reconcile, never blind-flip When a new fact contradicts what the corpus already says, stop and resolve the *shape* of the disagreement before writing: - **Staleness** — the corpus is simply out of date. Update in place; the old framing is wrong now. - **Axis** — both are true on different axes (a person can lead a business unit *and* report through a commercial line; a title and a functional role are not the same statement). Add the new axis; leave the still-true one. - **Ambiguity in the new fact** — the sentence that delivered the fact may parse two ways. Resolve the antecedent with the person who stated it before editing. A blind flip on a misread injects an error the corpus did not have. The cost asymmetry is the whole rule: re-reading and asking one question is cheap; a wrong edit propagated into a shared corpus is expensive and quiet. ## Provenance - Each merge writes a `log.md` line: date, the concept(s) touched, the fact, and the in-session source. - For a fact whose truth a future reader must trust or re-check, record the source explicitly in the concept too (`*Source: …*`), matching the corpus's existing citation style. - Treat the knowledge base as a cache, not the source of truth. A concept's `timestamp` records when it was last believed correct, not when it was last true. Re-verify before propagating a load-bearing fact outward. ## Tools ### `scripts/kb_scan.py` — pre-merge reconnaissance (read-only) ```bash # every existing mention of an entity, grouped by file (run before any merge) python3 scripts/kb_scan.py --entity "Full Name" --alias Surname --alias handle # inventory every concept with its OKF type and title python3 scripts/kb_scan.py --list # surface concepts whose frontmatter timestamp is older than a date (or missing) python3 scripts/kb_scan.py --stale 2026-01-01 ``` Stdlib only; read-only; excludes OKF-reserved `index.md`/`log.md` and `README.md`. The `--entity` scan is the mandatory step 3: it turns "I think this person is mentioned in the roster" into "here are the six exact lines that mention them," which is what makes an in-place merge possible. ## Integration - **`synthesis-okf`** validates conformance and configured metadata consistency after every merge. This skill governs *what* to write and *where*; OKF governs that the result stays structurally coherent. - **`synthesis-kb-edit`** owns repository policy and shipping. Pass it the touched files; do not independently reconstruct branch, host, scanner, or review mechanics from the capture config. - **`synthesis-context-lifecycle`** is the sibling for *project* working memory (CONTEXT/REFERENCE/sessions). This skill is its counterpart for the durable, cross-project knowledge base. Project state that has hardened into a stable fact graduates from a project's REFERENCE into the knowledge base via this skill. - **Daily rituals** are a natural trigger: a day-end step can ask "what did today teach that the knowledge base should hold?" and run this workflow on the answer. - **Repository configuration.** Read `.agents/knowledge-base.yaml`; do not discover client-specific workflow copies under a tool-owned skill folder. One portable config plus the public skills is the cross-agent contract. ## Commit hygiene - Stage only the files this merge touched. Never `git add -A` — a sibling process or a parallel agent may have staged unrelated work. - The commit message names the *area*, not the sensitive specifics: "Update key people directory," "Refresh product ownership," "Record a departure." Never put the person, the reason, or the prior value in the message. - Verify `git remote -v` before any push. Push only per the repo's config posture; hold for explicit approval on any shared or mirrored repo, and never push a private-tier repo to a shared remote. ## Related - `synthesis-okf` — the OKF format validator/converter this skill validates with. - `synthesis-kb-edit` — repository policy, validation orchestration, and configured ship flow. - `synthesis-context-lifecycle` — project working memory; the sibling layer. - `synthesis-message-guard` — the same provenance-and-fail-safe ethos, applied to outbound correspondence instead of stored knowledge.