# 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.