Knowledge Capture
Version 1.2.0 (2026-09-01) ships config.example.json and connects the
private routing table to the guided onboarding interview. The example uses a
synthetic private workspace and a hold-for-approval push posture; the onboarding
validator refuses a domain without its repo, tier, or bundle path.
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.
Run synthesis-onboarding init to author the file from the personal workspace
you select, or copy config.example.json and validate it with the onboarding
doctor. The public example contains no real repository or confidentiality data.
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.
- 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).
- 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.
- 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.
- 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).
- 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.
- 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.
- 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
- Scan first, always. No write without a completed
kb_scan.py for every
entity involved. The scan is the difference between merging and littering.
- 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.
- Reconcile, never blind-flip. When a new fact contradicts the corpus, the
contradiction is data, not a mandate to overwrite. See below.
- 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)
# every existing mention of an entity, grouped by file (run before any merge)
python3 scripts/kb_scan.py <bundle_dir> --entity "Full Name" --alias Surname --alias handle
# inventory every concept with its OKF type and title
python3 scripts/kb_scan.py <bundle_dir> --list
# surface concepts whose frontmatter timestamp is older than a date (or missing)
python3 scripts/kb_scan.py <bundle_dir> --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.
1---2name: synthesis-knowledge-capture3description: 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.4license: CC0-1.05depends_on:6 - synthesis-okf7 - synthesis-kb-edit8metadata:9 source: https://skillmd.com/skills/synthesisengineering/synthesis-knowledge-capture10 author: Rajiv Pant11 version: "1.2.0"12 source_repo: "github.com/synthesisengineering/synthesis-skills"13 source_type: "public"14---1516# Knowledge Capture1718**Version 1.2.0** (2026-09-01) ships `config.example.json` and connects the19private routing table to the guided onboarding interview. The example uses a20synthetic private workspace and a hold-for-approval push posture; the onboarding21validator refuses a domain without its repo, tier, or bundle path.2223**Version 1.1.0** (2026-07-29)2425A fact learned in a session and not written to the durable knowledge base is a26fact lost. This skill is the disciplined path from "the agent now knows X" to27"the knowledge base now knows X" — without duplicating, without overwriting a28still-true fact, and without leaking a confidential fact into a shared corpus.2930## Why it exists3132Most knowledge bases have a rule like *"update `source/` when you learn33something."* A rule is not a workflow, and a manual rule drifts. The failure has34three shapes, all real:3536- **Evaporation.** The corrected fact lives only in the session transcript. The37 next session starts blind and repeats the old mistake.38- **Duplication.** A naive append adds a second, contradictory concept. Now the39 corpus asserts two things and a reader cannot tell which is current.40- **Destruction.** A blind overwrite deletes a framing that was still accurate41 on a different axis, replacing signal with a plausible error.4243The canonical trigger: an agent learns a corrected fact about a person's role.44The corpus already holds several references to that person under a prior45framing. Evaporation loses the correction; duplication contradicts; a blind flip46destroys references that were right all along. The only safe path is: find every47existing mention first, decide in place, reconcile rather than flip, cite the48source. That path is this skill.4950## The configuration contract5152All routing specifics live in a PRIVATE config the skill reads at load time:5354```55~/.synthesis/knowledge-capture/config.json56```5758It maps knowledge **domains** to a target repo, a confidentiality **tier**, and59the OKF bundle path inside that repo; it names the **confidential terms** that60must never reach a public repo; and it records each repo's **push posture**61(auto, or hold-for-approval). This skill is generic and publishable; the config62is neither. If the config is missing, STOP and say so — routing a fact without63the routing table is guessing, and guessing about confidentiality is how a64private fact ends up in a shared corpus.6566Run `synthesis-onboarding init` to author the file from the personal workspace67you select, or copy `config.example.json` and validate it with the onboarding68doctor. The public example contains no real repository or confidentiality data.6970Each target repository must also carry `.agents/knowledge-base.yaml`. The71private capture config answers **which repository receives the fact**; the72repository contract answers **what may be edited there, which schema applies,73and how the change ships**. Stop if either layer is missing or they disagree on74the bundle path.7576## The capture workflow7778Run these in order. Never skip step 3.79801. **Extract.** From the session, list the *durable* facts — things true beyond81 this conversation: people, roles, reporting lines, product ownership,82 decisions and their rationale, stable technical facts. Exclude the ephemeral83 (today's task state, one-off logistics). State each as one atomic claim with84 its in-session source (who said it, which tool call surfaced it).852. **Route.** For each fact, choose the target from config by confidentiality86 tier (see Confidentiality routing). One fact may split: the neutral fact to a87 shared KB, the candid framing to a private one.883. **Scan before writing.** Run `kb_scan.py` for every entity the fact touches,89 across the target bundle. This returns *every* file and line that already90 mentions the entity. You cannot merge in place without first knowing every91 place the entity already lives. This step is mandatory; skipping it is how92 duplication and destruction happen.934. **Merge in place.** Update the concept that owns the fact (a person's94 directory entry, a product's page). Do not append a new dated note to a95 reference concept — reference tiers are updated in place. If the fact is96 genuinely new (a departure, a new hire), add it to the concept that already97 holds that class of fact (the departures table, the roster).985. **Validate.** Run both `synthesis-okf` layers: OKF conformance on the bundle99 and configured metadata consistency on every touched concept. Resolve all100 conformance errors, conflicts, and duplicates before shipping.1016. **Log provenance.** Append a `log.md` entry (`## YYYY-MM-DD`, newest first)102 naming what changed and the in-session source. `log.md` is OKF-reserved and103 excluded from compiled knowledge; it is the audit trail, not content.1047. **Ship through `synthesis-kb-edit`.** Hand the exact touched-file list and105 validation results to the configured editor workflow. It rechecks editable,106 refused, generated, confidentiality, branch, host, and review policy before107 staging or publishing anything.108109## Merge discipline — the four hard rules1101111. **Scan first, always.** No write without a completed `kb_scan.py` for every112 entity involved. The scan is the difference between merging and littering.1132. **In place, not append.** Stable facts are corrected where they live. A new114 concept file is for a genuinely new unit of knowledge, not for a fact that115 updates an existing one.1163. **Reconcile, never blind-flip.** When a new fact contradicts the corpus, the117 contradiction is data, not a mandate to overwrite. See below.1184. **No fact without a source.** Every merged claim cites its in-session origin.119 If you cannot name who said it or which tool surfaced it, you cannot write it120 — the same provenance bar the rest of the synthesis stack enforces.121122## Confidentiality routing123124- **Default to the most private tier that fits.** When unsure whether a fact125 belongs in a shared corpus, it does not. Route it private and flag the126 question.127- **Split neutral from candid.** Org-structure facts (title, reporting line,128 who owns a product) are usually fine for a shared internal KB. Candid framing129 (why someone left, a performance read, negotiation posture) is not — that is130 private, always, regardless of how the fact was learned.131- **A public repo takes no confidential term.** If the target is a public repo,132 the config's confidential-term list is a hard filter: any fact containing one133 is rerouted to a private target or dropped, never sanitized-and-shipped.134- **Learned-in-a-shared-channel is not permission.** Where a fact was surfaced135 does not set where it may be stored. The confidentiality tier of the *fact*136 governs, per config.137138## Reconcile, never blind-flip139140When a new fact contradicts what the corpus already says, stop and resolve the141*shape* of the disagreement before writing:142143- **Staleness** — the corpus is simply out of date. Update in place; the old144 framing is wrong now.145- **Axis** — both are true on different axes (a person can lead a business unit146 *and* report through a commercial line; a title and a functional role are not147 the same statement). Add the new axis; leave the still-true one.148- **Ambiguity in the new fact** — the sentence that delivered the fact may149 parse two ways. Resolve the antecedent with the person who stated it before150 editing. A blind flip on a misread injects an error the corpus did not have.151152The cost asymmetry is the whole rule: re-reading and asking one question is153cheap; a wrong edit propagated into a shared corpus is expensive and quiet.154155## Provenance156157- Each merge writes a `log.md` line: date, the concept(s) touched, the fact, and158 the in-session source.159- For a fact whose truth a future reader must trust or re-check, record the160 source explicitly in the concept too (`*Source: …*`), matching the corpus's161 existing citation style.162- Treat the knowledge base as a cache, not the source of truth. A concept's163 `timestamp` records when it was last believed correct, not when it was last164 true. Re-verify before propagating a load-bearing fact outward.165166## Tools167168### `scripts/kb_scan.py` — pre-merge reconnaissance (read-only)169170```bash171# every existing mention of an entity, grouped by file (run before any merge)172python3 scripts/kb_scan.py <bundle_dir> --entity "Full Name" --alias Surname --alias handle173174# inventory every concept with its OKF type and title175python3 scripts/kb_scan.py <bundle_dir> --list176177# surface concepts whose frontmatter timestamp is older than a date (or missing)178python3 scripts/kb_scan.py <bundle_dir> --stale 2026-01-01179```180181Stdlib only; read-only; excludes OKF-reserved `index.md`/`log.md` and182`README.md`. The `--entity` scan is the mandatory step 3: it turns "I think this183person is mentioned in the roster" into "here are the six exact lines that184mention them," which is what makes an in-place merge possible.185186## Integration187188- **`synthesis-okf`** validates conformance and configured metadata189 consistency after every merge. This skill governs *what* to write and190 *where*; OKF governs that the result stays structurally coherent.191- **`synthesis-kb-edit`** owns repository policy and shipping. Pass it the192 touched files; do not independently reconstruct branch, host, scanner, or193 review mechanics from the capture config.194- **`synthesis-context-lifecycle`** is the sibling for *project* working memory195 (CONTEXT/REFERENCE/sessions). This skill is its counterpart for the durable,196 cross-project knowledge base. Project state that has hardened into a stable197 fact graduates from a project's REFERENCE into the knowledge base via this198 skill.199- **Daily rituals** are a natural trigger: a day-end step can ask "what did today200 teach that the knowledge base should hold?" and run this workflow on the201 answer.202- **Repository configuration.** Read `.agents/knowledge-base.yaml`; do not203 discover client-specific workflow copies under a tool-owned skill folder.204 One portable config plus the public skills is the cross-agent contract.205206## Commit hygiene207208- Stage only the files this merge touched. Never `git add -A` — a sibling209 process or a parallel agent may have staged unrelated work.210- The commit message names the *area*, not the sensitive specifics: "Update key211 people directory," "Refresh product ownership," "Record a departure." Never212 put the person, the reason, or the prior value in the message.213- Verify `git remote -v` before any push. Push only per the repo's config214 posture; hold for explicit approval on any shared or mirrored repo, and never215 push a private-tier repo to a shared remote.216217## Related218219- `synthesis-okf` — the OKF format validator/converter this skill validates with.220- `synthesis-kb-edit` — repository policy, validation orchestration, and221 configured ship flow.222- `synthesis-context-lifecycle` — project working memory; the sibling layer.223- `synthesis-message-guard` — the same provenance-and-fail-safe ethos, applied to224 outbound correspondence instead of stored knowledge.