Knowledge

Knowledge is reference material: files that already have the answers, made available to agents so they can use the detail when it is relevant.

It is the answer to “this is written down somewhere else already”. An API contract, a data dictionary, a partner’s integration guide, a compliance standard, the spreadsheet that defines your product’s tiers.

Why it is not instructions

Instructions are rules that apply every time. Knowledge is detail that applies when it comes up.

The practical test is length and shape. “Money is always integer minor units” is a rule, and belongs in instructions. A forty-page payment provider integration guide is not a rule, and putting it in instructions would attach it to every piece of work whether or not it is about payments.

Content in the wrong one is the most common way to be surprised by an agent’s output. Policies, Instructions and Knowledge covers how the three kinds divide.

Where it lives

Knowledge exists at the organization, the factory and the product, and narrows as it comes down.

Put a file at the level where it is relevant. An industry standard your whole company works to belongs at the organization. A partner integration only one factory deals with belongs to that factory. A schema specific to one codebase belongs to the product.

Putting everything at the organization is the tempting mistake. It does not break anything, but it makes the pool of reference material larger and less specific for every product you have.

What to add

You do not have to come to this page to add it. A file attached in a product’s Discovery conversation lands in that product’s knowledge base the same way, and stays after the conversation ends.

The good candidates share a property: they are things a competent new engineer would be handed and told to read before touching something.

• Specifications and contracts you have to conform to.
• Domain reference: glossaries, code lists, taxonomies.
• Third-party documentation for services you integrate with.
• Existing internal write-ups that would otherwise be retyped into a spec.

The poor candidates are things that change faster than you will remember to update them, and anything that is really a rule dressed up as reference material.

How agents actually use it

Knowledge is not attached to a piece of work and it is not handed over wholesale. An agent searches it when the work calls for it, and what it searches is fixed by the scope it is running in: that product, its factory, and the organization above them.

Two things follow from that. An agent cannot reach another factory’s material, because the boundary is set before the agent runs rather than asked of it. And the more material sits at the organization, the more there is to search through for every product you have.

An uploaded file is not usable the moment it lands. It is processed first, and a file can fail processing, which shows on the file itself and can be retried. A file that never finished processing is not being read by anything.

Who can manage it

Reading is open to everyone who can see the scope.

Writing depends on the level. Members can add, edit and delete knowledge on their factories and products, which is the point: the person who notices a file is missing can add it rather than filing a request.

Organization knowledge is different. Adding, changing or removing it takes an owner or admin, because it is inherited by every factory and product underneath and is governance in the same sense the policies are. Everyone can still read it.

Keeping it honest

Stale reference material is worse than none, because it is confidently specific.

Knowledge does not expire on its own and nothing warns you it has aged. When you replace a provider, retire a standard, or change a schema, the old file is still sitting there being read.