The Write Path: Capturing Knowledge and Earning Trust

For thirty years the bottleneck in organizational knowledge was retrieval. People wrote things down and could not find them again, so the rational response was to invest in search.

That bottleneck is largely gone. Semantic retrieval over a well-connected corpus finds the document, and a language model reads several and answers in prose.

Which relocates the constraint rather than removing it. The limit on what a company brain can tell you is now, almost entirely, what was written down in the first place. The first lesson's three jobs make this concrete: lookup works because the answer already exists as text, synthesis works when the underlying material exists, and rationale fails because the reasoning was never externalized.

So the highest-leverage work on a company brain is usually not on the brain. It is on the practices that determine what enters it. That is an unwelcome finding for a project staffed with engineers, and ignoring it is the single most common way these systems disappoint.

The instinctive response is a campaign: everyone should write more down. It fails for the same reasons it failed in the 1990s, and the reasons are structural rather than cultural.

The cost is immediate, concrete, and borne by the author. The benefit is deferred, diffuse, and captured by other people, possibly years later, possibly by someone who has not joined yet. That asymmetry loses to every urgent thing.

Documentation written as a separate task also lands in a separate place, disconnected from the work, and it ages the moment the work moves on.

And nobody is evaluated on it. In most organizations, writing down the reasoning behind a decision appears in no review criterion.

The conclusion is not that people are lazy. It is that a capture practice which depends on goodwill will decay, so the useful designs make capture a side effect of work that was going to happen anyway.

The best-established answer to the rationale problem comes from software engineering. Michael Nygard proposed architecture decision records in 2011, and Martin Fowler's write-up helped make them common practice.

An ADR is a short document capturing one decision and, crucially, the reasoning around it. The standard skeleton is four sections. Context: the forces in play, the constraints, what was true when the decision was made. Decision: what was chosen, stated plainly. Consequences: what this makes easier, what it makes harder, what is now expensive to reverse. Status: proposed, accepted, or superseded.

Three design choices do the work. ADRs live in the repository next to the code, so they are versioned with the thing they describe and are found by people already working there. They are written at decision time, when the reasoning is still available, rather than reconstructed later. And they are immutable: when a decision changes you write a new ADR that supersedes the old one, and you never edit or delete the original.

That last rule is what preserves the history, which is exactly the thing the first lesson identified as missing.

Concretely, this is what a good one looks like. Note how much of the value is in the sections that are not the decision itself.

# ADR 0014: Use early-binding ACLs in the knowledge index

## Status
Accepted (2026-03-11). Supersedes ADR 0009.

## Context
Query latency budget is 400ms end to end. Late binding needs one
callback per candidate document; at 50 candidates our SharePoint
tenant rate-limits us within 3 concurrent users. Compliance requires
revocations to take effect within 15 minutes.

## Decision
Store ACLs in the index at ingestion. Subscribe to permission-change
webhooks; fall back to a 10-minute reconciliation sweep.

## Consequences
+ Query is a single filtered index call; latency budget holds.
- The index holds a copy of permissions: a revocation is live only
  after the webhook lands. The 10-minute sweep bounds this.
- Ties us to sources that emit permission-change events. Adding a
  source without them requires revisiting this ADR.

The Context section is what a company brain can retrieve two years from now when someone asks why the index holds its own copy of permissions. Without it, the answer is a shrug and a re-litigation.

ADRs generalize into a design principle: attach capture to a moment that already exists in the workflow, rather than creating a new one.

The pull request already exists, so a template field asking why this approach costs seconds and lands the reasoning next to the diff.

The incident review already exists, so a postmortem written from a standard template turns an outage into a durable, searchable lesson.

The support ticket already exists, so a resolution note in a structured field becomes the answer for the next person with the same problem.

The project already ends, so a short closeout note captures what would be done differently.

The rule of thumb is that capture must be cheaper than the interruption it prevents. If writing the note takes longer than answering the question again next month, people will correctly choose to answer it again. This is also where a language model helps on the write side rather than the read side: drafting a postmortem or a decision record from a chat transcript, for a human to correct, moves the cost from writing to reviewing, and reviewing is much cheaper.

The 1990s repositories had authors but no owners, and that distinction is the one that decides whether a corpus stays true.

An author wrote a document once. An owner is accountable for it being correct now. Assigning ownership by team rather than individual is what survives turnover.

Time-based review, resurfacing every document annually, is the common approach and it is weak: it generates a large periodic pile of low-value work, and it catches drift on average six months late.

Change-triggered review works better. Bind the review to the event that actually invalidates the document. When an API version ships, the integration docs referencing it are flagged. When a policy is superseded, the pages linking to it are flagged. When a service is decommissioned, its runbooks are flagged. The trigger comes from a system that already knows the change happened.

A lifecycle state on every document, approved, draft, or deprecated, then feeds directly into the ranking signals from the previous lesson. Deprecated content should not be deleted, because historical questions are legitimate, but it should be demoted and clearly labelled when cited.

Usage is not a quality metric. A system people query daily and quietly distrust looks identical, in a dashboard, to one that works.

Build a golden set: fifty to two hundred real questions taken from actual support channels and onboarding threads, each with a verified correct answer and the document it should come from. Real questions, because synthetic ones are phrased the way the corpus is written and hide exactly the vocabulary mismatch you need to test.

Then measure four things separately, because they fail independently.

Retrieval: did the correct document appear in the retrieved set at all? A failure here is a connector, chunking, or ranking problem.

Groundedness: is every claim in the answer supported by a retrieved passage, or did the model fill a gap? This is the hallucination check.

Correctness: is the answer actually right? Retrieval can succeed and synthesis still mangle it.

Abstention: when the corpus does not contain the answer, does the system say so? Test this deliberately with questions you know are unanswerable. A system that never says I do not know is not trustworthy, it is just confident, and abstention is the behaviour most worth engineering for.

Retrieval quality is measured with a set of questions that should return documents. Permissions require the opposite: a set that must not.

Construct a must-not-retrieve suite. Take a handful of genuinely sensitive documents, unreleased financials, a compensation band, an acquisition codename, an HR case file. For each, write questions whose answer lives in that document. Then run those questions as a user who should not have access, and assert that neither the document nor its content appears in the answer.

Run it on every change to the ingestion pipeline, on every connector added, and on a schedule to catch drift. Include the timing case: narrow a document's sharing at the source, then query as a now-unauthorized user and assert the content disappears within your stated reconciliation window. That single test exercises the exact exposure early binding introduces.

This suite is cheap, and it is the difference between believing your permission model works and knowing it. Access control that has never been tested adversarially should be assumed broken, because the failure mode from the previous lesson is invisible in normal use.

Five failure modes account for most of the disappointment, and each has a tell you can watch for.

The demo trap. A prototype over a clean folder of exported documents works beautifully, gets funded, and then meets real connectors, real permissions, and a real corpus. The tell is a demo whose corpus nobody had to negotiate access to.

Garbage in, fluent garbage out. The corpus is stale and contradictory, so the system produces confident wrong answers. The tell is a rollout with no corpus cleanup phase.

The trust cliff. Users do not degrade gracefully. A handful of confidently wrong answers early on, and people stop asking, permanently. Recovering trust is far harder than earning it, so a narrow accurate launch beats a broad unreliable one.

Oversharing discovered in production. Covered in the previous lesson. The tell is any plan where the permissions audit comes after go-live.

The write side never addressed. The system answers lookup questions well and cannot answer why, so it is perceived as a better search box, which is what it is. The tell is a project plan with no capture workstream in it.

Putting the three lessons together, the sequence that works runs narrow to broad, and treats trust as the scarce resource.

Pick one domain with a real, measurable pain: employee onboarding questions, or support agents looking up product behaviour. One domain means one corpus you can actually clean.

Audit and remediate permissions on that corpus before indexing it.

Build the golden set and the must-not-retrieve suite before launching, not after, so you have a baseline to compare against.

Launch to a small group who will report problems rather than quietly stop using it.

Add the capture practice for that domain in parallel: decision records, resolution notes, a change-triggered review on its documents.

Expand only when the golden set holds and the users of the first domain would object to it being taken away. That last condition is the real signal, and it is worth more than any usage dashboard.

The honest summary of all three lessons: the technology is the easy part, the permissions are the risky part, and what your organization actually writes down is the part that decides whether any of it was worth doing.