trail-record
Skill0 starsChanged 3 months agoMITView on GitHub
Writes the decision record for a piece of AI-assisted work — what was asked, what was decided and by whom, what was rejected, where the operator corrected the agent, and what was assumed. Anchored to a real commit range so it cannot drift into fiction. Use at the end of a working session, before a PR, when handing work to someone else, or when asked to document what just happened. Writes .trail/entries/. Триггеры — "запиши что сделали", "зафиксируй решения", "оформи сессию", "что мы тут решили", "документируй изменения", "record this", "закрой сессию".
In this repository3 other files it gives its agents.
- trail-distilSkill
- trailSkill
- trail-whySkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Write the record in the language the work was conducted in.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Record
Git records what changed. This records why, whose decision it was, and what was rejected — the part that decides whether the next person can safely touch the code.
The thing that is actually lost. A diff is recoverable forever. The conversation that
produced it is gone when the session ends: what the operator asked for, what the agent
proposed, where the operator said "no, not like that", and what the agent did instead.
Six months later git blame names a commit. It cannot say that the obvious approach was
tried and rejected for a reason that still holds.
Language
Write the record in the language the work was conducted in. If the operator spoke Russian, the record is Russian — it is read by the same people who did the work.
Quote the operator verbatim, in their own words, never translated and never paraphrased. A paraphrase has already decided what they meant, and the whole value of the correction sections is that they preserve what was actually said.
Answer in the conversation, not only in the file
Lead with what the record found, not with the fact that you wrote one:
- The decisions worth remembering — two or three lines
- The corrections — where the operator redirected, and what it implies about this project
- What is assumed and could be wrong
- Where the entry lives — one line
A developer who reads only your first ten lines should learn something they did not already know from watching the session.
Before anything: is this repository set up?
git rev-parse --show-toplevel 2>/dev/null || echo "NOT A GIT REPOSITORY"
ls .trail/config.yaml 2>/dev/null || echo "not initialised"No git means no anchor. Say so plainly and offer to write an unanchored entry — it is worth much less, because nothing ties it to code that can be read, and it will be believed anyway. That is the trade the operator should make knowingly.
First run in a repository: read references/init.md and create .trail/ from what the
repository already tells you. It is four detections and no questions.
Anchor first, write second
Read references/anchor.md before writing anything. An entry that does not name the
code it describes is a story. The anchor is what makes it checkable a year later, and
getting it wrong is worse than omitting it — a record pointing at the wrong commits sends
the reader to unrelated changes and quietly discredits every other entry.
git status --short
git log --oneline "$(git rev-parse --abbrev-ref HEAD)" -10Establish the range before you start describing, because the range decides scope: what is inside it belongs in this entry, what is outside it does not, however recently you touched it.
What goes in — four kinds of thing, and only four
Read references/entry.md for the exact shape. The skill's whole discipline is in
what qualifies:
| Qualifies when | Does not qualify | |
| DECIDED | a competent alternative existed and you picked one | there was only one way to do it |
| REJECTED | it was seriously considered and dropped | everything you did not do |
| CORRECTION | the operator changed the direction of the work | the operator asking a question |
| ASSUMED | you proceeded without knowing, and being wrong has a cost | ordinary inference from the code |
Everything else is narration, and narration is what makes a record too long to read and therefore unread.
Every decision carries its source
The field that makes this different from a commit message:
- DECIDED [operator]: <what>
- DECIDED [agent]: <what>
- DECIDED [project]: <what>| Source | Means | Why it matters later |
operator | a person chose this, in this session | not yours to revisit alone |
agent | the model chose, and nobody objected | the one to re-examine first — it may be a default, not a decision |
project | a rule, config or convention already in the repository decided it | changing it changes more than this code |
agent is the honest and uncomfortable one. Work done with an AI is full of choices
nobody consciously made; marking them is what lets a reviewer find them. A record where
everything is [operator] is a record that has flattered the operator and hidden the
model's own choices.
The corrections are the point
Where the operator said "no, do it differently" is where the model's default diverged from this project. That is the single most valuable line in the file, and it is the one the agent writing the record is least inclined to include.
- CORRECTION: <what the agent did or proposed>
→ оператор: "<verbatim>"
→ стало: <what changed>
→ правило: <what this implies for next time — or "разовое">On a session with more than one operator turn, this section may not be empty by default. If the operator spoke twice, the second time they refined, redirected or confirmed — and the first two are corrections. An empty section is allowed only with a sentence saying why: a single-turn session, or every later turn was an unrelated new task.
The правило line is what trail-distil later turns into project rules. Write it even when it
feels obvious; obvious-to-you is the definition of what does not get written down.
Time-box it, or it will not get written
Ten minutes, one entry, no research. The record describes what you already know from having done the work. If writing it requires re-reading the diff to remember what happened, the entry is being written too late — say so, write what is recoverable, and mark the rest as lost.
An entry that costs as much as the work does not survive contact with a deadline.
Do not write fiction, and do not write a diff
Two failure modes, opposite directions:
| Failure | Looks like | Fix |
| Fiction | a tidy narrative where every decision looks justified | cite the anchor for each claim; if you cannot, drop the claim |
| A second diff | a list of files and what changed in each | that is git show; write only what the diff cannot say |
The test for any line: could git log -p tell the reader this? If yes, delete it.
Non-goals
- Committing, pushing, or opening anything. The entry is written to the working tree.
- Replacing the commit message. A good commit message still belongs in the commit.
- Recording every action. Four kinds of thing qualify; the rest is noise.
- Judging whether the work was good — that is a review.
- Reading the whole repository to write an entry. Ten minutes, from what you already know.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

