agentleFS
MichaelTarasov02MichaelTarasov02/Trail/skills/trail-record/SKILL.md

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", "закрой сессию".

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
  1. Distinctive:

    Write the record in the language the work was conducted in.

    line 19

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. The decisions worth remembering — two or three lines
  2. The corrections — where the operator redirected, and what it implies about this project
  3. What is assumed and could be wrong
  4. 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)" -10

Establish 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 whenDoes not qualify
DECIDEDa competent alternative existed and you picked onethere was only one way to do it
REJECTEDit was seriously considered and droppedeverything you did not do
CORRECTIONthe operator changed the direction of the workthe operator asking a question
ASSUMEDyou proceeded without knowing, and being wrong has a costordinary 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>
SourceMeansWhy it matters later
operatora person chose this, in this sessionnot yours to revisit alone
agentthe model chose, and nobody objectedthe one to re-examine first — it may be a default, not a decision
projecta rule, config or convention already in the repository decided itchanging 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:

FailureLooks likeFix
Fictiona tidy narrative where every decision looks justifiedcite the anchor for each claim; if you cannot, drop the claim
A second diffa list of files and what changed in eachthat 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.