Inside the layer
One note from the layer's knowledge base, in full
A markdown knowledge base is the set of plain-text files holding the rules an automated workflow follows — one rule per note, in the client's own storage. Each note carries frontmatter, the rule itself, its tolerances, and links to related notes. An operator edits a note; the next run follows the new rule.
What a markdown knowledge base is
The layer's knowledge base is plain text in your storage — the rules it follows, the exceptions your people taught it, and which system it believes when two of them disagree. Versioned like code, readable by an auditor, editable by an operator.
One rule per file, in the storage the client already runs. No schema to learn, no console to open. Below is one of those files, published whole; everything after it is annotation.
The specimen: one note, published in full
ops/vendor-onboarding.md as it sits on disk — nothing redacted, nothing reformatted.
--- agent: invoice-matcher workflow: purchase-order-reconciliation scope: accounts-payable updated: 2026-07-18 confidence: high source: operator-correction --- # Line order is not line identity Invoices from this vendor list line items in a different order than the purchase order. Match on SKU, never on line position. Position matching passed review for six weeks because the first vendors we onboarded happened to preserve PO order. It is not a rule, it is a coincidence — see [[po-matching-policy]]. ## Tolerance - Unit price: ±2% - Quantity: **exact**, no tolerance - Freight: ignored, reconciled separately in [[freight-accrual]] Anything outside tolerance goes to [[escalation-queue]]. It is never auto-approved, regardless of confidence score. An operator decides. ## Why this note exists Three invoices auto-approved against the wrong lines because quantities matched by position. Caught at month-end, not by the agent. The fix was not a better model. The fix was writing down what "matching" actually means here, so the agent stops inferring it — see [[incident-2026-06-14]] for the full trace. ## Open Two vendors send consolidated invoices covering several POs. Current behaviour splits them, which is wrong about a third of the time. Not yet solved — tracked in [[consolidated-invoice-handling]]. --- *This note is read and updated by the agent on every run. It is a plain markdown file in the client's own storage. Anyone can open it, read it, correct it, and the agent's behaviour changes on the next run.*
The frontmatter, field by field
| Field | Value here | What it is for |
|---|---|---|
agent | invoice-matcher | Which worker reads the note. A rule belongs to what applies it, not to a folder. |
workflow | purchase-order-reconciliation | The process it belongs to, so it cannot be applied outside it. |
scope | accounts-payable | What stops a matching rule leaking into another ledger. |
updated | 2026-07-18 | When the rule last changed. The first date an auditor asks for. |
confidence | high | How settled it is. See below. |
source | operator-correction | Where the rule came from — here, a person rather than a model. |
confidence: high is a value this note carries, not a defined scale. Nothing in the sources sets levels or thresholds, so nothing here describes them.
The rule, written so it cannot be inferred
Invoices from this vendor list line items in a different order than the purchase order. Match on SKU, never on line position.
ops/vendor-onboarding.md
Most rule sets stop there. This one also records why anyone would have got it wrong:
Position matching passed review for six weeks because the first vendors we onboarded happened to preserve PO order. It is not a rule, it is a coincidence — see po-matching-policy.
ops/vendor-onboarding.md
Tolerances live in the note, not in the code
- Unit price: ±2%
- Quantity: exact, no tolerance
- Freight: ignored, reconciled separately in freight-accrual
Anything outside tolerance goes to escalation-queue. It is never auto-approved, regardless of confidence score. An operator decides.
ops/vendor-onboarding.md
A confidence score does not buy an approval here. Widening the price band is an edit to one line of text — a diff with a date and a name on it. Read as accounts-payable mechanics, the same rules are on the invoice matching page.
How one note reaches the others
A rule usually only makes sense beside the rule it defers to. This one points at five.
- po-matching-policy — the general policy this vendor rule is an instance of
- escalation-queue — where anything outside tolerance goes
- freight-accrual — the separate reconciliation freight is excluded into
- incident-2026-06-14 — the trace of the failure that produced this note
- consolidated-invoice-handling — the case it admits is not solved
Those are this note's outbound references. Only ops/vendor-onboarding.md is published here.
Why this note exists, and why that section is in the file
Three invoices auto-approved against the wrong lines because quantities matched by position. Caught at month-end, not by the agent.
ops/vendor-onboarding.md
The fix was not a better model. The fix was writing down what "matching" actually means here, so the agent stops inferring it.
ops/vendor-onboarding.md
Inference is the failure mode. Hand a capable model an invoice and a purchase order and it will find a correspondence — on a well-behaved vendor, the right one. The knowledge base is where an operation stops relying on that.
The Open section: writing down what is not solved
Two vendors send consolidated invoices covering several POs. Current behaviour splits them, which is wrong about a third of the time. Not yet solved — tracked in consolidated-invoice-handling.
ops/vendor-onboarding.md
A case named as unsolved is a case the agent does not quietly decide. A rule set with no open section is either finished, which no operation is, or not telling you.
A worked correction: before and after
The note carries source: operator-correction because that is what happened to it. A reviewer changed one line:
No redeploy, no retraining, no release window, no engineer — because the rule was a line in a file. That is also how a layer differs from an RPA script, where the same change is an engineer re-recording a path.
Auditable, correctable, portable
Auditable
Every rule the layer follows is a line a person can open and read. No interface, no export request, no asking us.
Correctable
A reviewer edits the rule. The next run behaves differently. No redeploy, and the change is attributable.
Portable
Plain text outlives the model, the vendor and us. It stays readable whoever you work with next.
Why plain text and not a database
A rules database is faster to query and much harder to leave: the rules become rows in someone else's schema, exportable on someone else's terms. Markdown has none of that leverage, which is the point. It diffs in the version control the client already runs and stays readable whoever they work with next.
The trade is real — no query language, no referential integrity, no enforcement that a note is well formed. For a rule set an operations team owns and reads, it has been the right one.
How the rules get into the notes in the first place
Two routes in, and neither is a workshop producing a document nobody opens again. The first is the mapping phase: we map what your systems actually hold, where they contradict each other, and which rules exist only in people's heads.
The second is correction — the route this note took. "Captures the rules that exist only in your people's heads" in an interview produces a hypothesis. It becomes knowledge the first time it is wrong in production and the fix lands in the file rather than in a conversation.
Questions
Straight answers.
How do you capture the rules that only exist in people's heads?
Two ways. The mapping phase asks which rules exist only in people's heads and writes them down as notes. Then production corrects them: the layer applies a written rule, gets one wrong, and an operator edits the note. That correction is the capture, and it carries the corrector's name.
Why store business rules in plain text?
Because plain text is auditable, correctable and portable. Anyone can open a rule and read it without an export request, a reviewer can change it without a release, and it diffs in the version control you already run — so every change has a history, an author and a date.
Can a business user correct an automation without a redeploy?
Yes. The rules are markdown files, not code. A reviewer edits the line and the next run follows the new rule — no redeploy, no model change. The edit is a diff in your own version control, so the correction carries the person's name.
Why use markdown for a knowledge base?
It is readable by a person and parseable by a machine without either giving anything up. Frontmatter carries the fields, the body carries the rule in the operation's own words, wikilinks carry the connections. No schema to learn, no interface between the rule and whoever owns it.
What is tacit knowledge in business operations?
The rules that govern the work but exist only in people's heads: which supplier is always late, which mismatch is safe to wave through, which exception goes to whom. It is invisible on a system diagram, and it is the first thing an automation gets wrong.
Where does the knowledge base live?
In the client's own storage, as plain files. Not an export from a system of ours, and not held behind an interface. The layer reads those files on every run; the client's team reads and edits the same files, in the version control they already use.
Start here
Bring us one workflow.
Tell us the process that crosses the most systems. You get a scope, a measure and a delivery plan back — and a straight answer if we think it is not worth building.
Get in touch