ai-note

ai-note — save what it cost you to find out

What it produces

A block in the repository's DECISIONS.md. One decision, one ## D-NNN block, with the sections below. Or, when the finding belongs in the docs, prose handed to ai-write. This skill creates no file of its own.

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. Append one block. Do not rewrite an older block. The heading is the id the git floor counts:

   ## D-NNN: <what we do, in one line>
   
   Status: Accepted · Date: YYYY-MM-DD
   
   ### Context
   
   What forced the choice. Include `found`, `commit`, the files it describes, and `still_true_when`, so a later reader can tell if it rotted.
   
   ### Decision
   
   What we do, specific enough to check in the code.
   
   ### Consequences
   
   - What this makes easy
   - What this rules out
   
   ### Alternatives considered
   
   - **<Option>:** why not
   

3. The Decision is the value. Context is why anybody will believe it.

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 DECISIONS.md 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 stops being 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.