What's worth logging
The ledger is only useful if what's in it is worth finding. Too little, and the same questions get asked again. Too much, and the answer is buried. This page gives you one test and a set of examples from different teams.
The regret test
Before recording something, ask: would a future person or agent regret not knowing this?
If the answer is yes, record it. Typical yeses:
- a decision, with its reason and the options you rejected;
- a root cause that took real effort to find;
- a workaround for a known issue;
- an interpretation of a rule or policy that others will need to apply the same way;
- an option you tried or evaluated and turned down, and why;
- an exception you granted, and its conditions;
- a finding from an investigation, even if nothing changed because of it.
If the answer is no, leave it out. Typical noes:
- something another system already records well, such as a commit message, a ticket's status or a calendar entry;
- a routine action with nothing to learn from it;
- a restatement of a document that is already indexed, since search finds the document itself;
- progress updates with no finding in them;
- anything that is only true for the next hour.
Examples by team
| Team | Worth logging | Noise |
|---|---|---|
| Engineering | We chose Postgres over MySQL for the ledger, and why | Renamed a variable |
| Engineering | We rejected library X: it has no builds for our servers' processors | Upgraded a dependency to a patch release |
| Support | Known issue: exports fail above 10,000 rows. Workaround: split the date range | Closed ticket 4411 |
| Support | Refunds over $500 need a team lead's approval | Replied to a customer |
| Legal | How we read the liability cap in the standard reseller agreement | Sent an NDA for signature |
| Legal | We rejected vendor Y: its data-processing terms allow no audits | Booked a call with vendor Y |
| People | The parental leave policy applies to contractors on 12-month terms, as confirmed by the HR lead | Updated one employee's address |
| IT & operations | Kiosk laptops are exempt from the screen-lock rule, on two conditions | Reset a password |
| Product | We dropped bulk editing from this quarter's plan: two customers' needs conflict | Moved a card on the board |
Illustrative
These examples are not real data.
Keep sensitive details out
Everyone with access to a namespace can read every topic in it. There are no per-topic permissions.
- Record the rule, not the person. "The leave policy covers contractors on 12-month terms" is worth logging; one person's leave request is not.
- Never record passwords, API keys or other secrets. Agents can quote anything they find.
- Keep HR and legal topics in their own namespace, so only the people who should see them can.
Keep each topic small
A topic that passes the test should still hold one thing:
- one decision or one finding per topic;
- a title that states the decision or the finding;
- a summary that frames the question;
- a current state of a few sentences.
See Recording decisions and Incidents & defects for how each part reads.
Tell your agents
Agents record what their instructions tell them to. Put the regret test in your agent instructions, for example:
md
## The ledger
- Before a non-obvious decision, or before investigating a problem again, search the ledger.
- When you finish a task, record what a future teammate would regret not knowing:
a decision and why, a root cause, a workaround, or an option you rejected.
- One topic per decision or finding. Don't record trivia, secrets or personal details.If noise gets in anyway, archive it. Archiving hides the topic from search but keeps it in the ledger.