ai-note

Save what it cost you to find out

What it produces

docs/notes/<slug>.md, committed, with a header that lets rot be detected. A note is appended to with a fresh date, never rewritten — the history a finding records cannot be silently edited.

Steps

1. The bar is thirty minutes. If it took less than that to work out, it will take less than that again, and a note about it is noise that hides the ones that matter.

2. Write the header first — it is what makes the note checkable later:

   found: 2026-08-08
   commit: 4f2a91c
   describes: ["src/ai_engineering/wiring.py", "policy/surfaces.toml"]
   still_true_when: "the settings writers still merge rather than replace"
   

3. Write the note in three parts and no more: what you expected, what actually happened, and what to do about it. The middle one is the value; the first one is why anybody will believe you.

4. Point at the evidence. The command you ran, its output, the line in the vendor's source. A note whose claim cannot be re-checked becomes folklore within a quarter.

5. If the note is a workaround, say what would remove the need for it, and where that fix would live — upstream, in our code, or in a decision somebody has to make.

6. Searching: git grep over docs/notes/ is the whole query engine, and it is enough at this size. Read the header of anything you find and check still_true_when before you act on it.

7. When a note is no longer true, delete it in a commit that says why. A wrong note is worse than no note, because it is trusted.

8. Persistence beyond this repository is not this skill's work and not this framework's. The note is committed markdown in the user's own repository, which is where it can be reviewed, dated and deleted; whatever memory system the host provides keeps its own copy on its own terms. A learning store inside the framework would be a second source of truth for something git already versions, and the second one is always the stale one.