Entry types
Rule, fact, pitfall: three kinds of knowledge, told apart by what each one changes for whoever reads it.
There are three types, and they differ not by “genre” but by what changes for whoever reads the entry.
| Type | What it changes for the reader |
|---|---|
| Rule | “Always follow this” — this is how we decided to work |
| Fact | “Know how things are here” — nobody chose this, it just is |
| Pitfall | “If you hit it — here is the way around” — an obstacle and how to get past it |
Rule
Always follow this. A norm set by a person: how work is done here.
“YAGNI, always: we do not build ‘for the future’” “We answer and comment in Russian; entity names are in English” “Do not add dependencies without agreement” “We answer a customer within one working day” — a department’s rule in a space without code
Decisions taken belong here too, if they prescribe how to act: “we publish upstream only through a PR, because…”. The reason in the entry body matters more than the decision itself: without it, in a month the rejected approach will be proposed again.
Rules are written by a person. The AI does not create rules: its business is observations, not directives. For the model, a rule written by a person is an instruction, not a hint.
Fact
Know how things are here. Something that cannot be worked out from the code in reasonable time — and that nobody chose: it simply is so.
“This is a project reverse-engineering such-and-such protocol” “The reports module is legacy, it is being rewritten, no large changes there” “Payments go through an external gateway; the test environment is at such-and-such address, access via VPN” “The current price list is in the Sales/Price lists folder” — a department’s fact in a space without code
The addresses of test environments, dashboards and documents are facts too: they describe where things are.
Facts are written by both people and the AI.
Pitfall
If you hit it — here is the way around. A reproducible obstacle together with a way to get past it.
“Tests fail without the environment up: bring it up first, then run them” “Importing a large file times out — load it in parts” “The 2024 procurement regulation is outdated — use the 2026 edition” — a pitfall in a department’s documents
Pitfalls are most often written by the AI: it is the one stepping into them. A pitfall differs from a fact in that it carries an action: not “this is how it is” but “if you get stuck — do this”.
How to choose in a second
Ask yourself what should happen in the head of whoever reads it:
- should do it this way → rule;
- should take it into account → fact;
- should know the way around if stuck → pitfall.
Why exactly three types
There used to be five: “link” and “agreement” as well. Both turned out to be special cases. A test environment’s address is a fact about the project, and a decision taken is either a rule (“we do it this way”) or a fact (“this is how everything works now”). The extra choice in the form added no precision, it added doubt — which of the five to pick. Three kinds, told apart by action, are chosen without thinking.
Entry
What a piece of knowledge consists of: title, one-line description, type, scope, body and two flags. How to write it so the model uses it.
Organisation, project, task
Knowledge of the whole organisation, one project or one task: what goes where, who sees it, and what happens to a task’s entries when it closes.