Record a session

Principles in play: Track records.TRACETrack records

A trace record is a record of human direction and machine execution. It keeps what you asked for in your own words, what the agent chose, and what it did and did not check, so that a collaborator can examine the work’s relation to the intended task. Every agent session that commits work keeps one; a commit you type yourself owes none. Your agent drafts it privately and brings it up to date before each commit, and it joins the project with the work it records.

Steps

1. Give your task in your own words.

   Say to your agent

   Compare the two groups in the yearly table and tell me whether the difference holds in every year.

   Your agent drafts the record in an ignored folder under workspace/record-staging/, and names you there from your Git name, unless that reads as a model’s name or you give it another. When it makes a consequential choice, it records the choice there and then, with why it took it over the alternatives and what it used, rather than at the end of the session.

2. Read the draft.

   Say to your agent

   What did you check, what did you check it against, and what did you not check?

   evidence.json holds your exact words, summary.md what was chosen, decisions.jsonl each consequential choice with its reason, and checks.jsonl the checks, with what they did not cover under limits.

3. Say where a passage came from, when it matters.

   Say to your agent

   In my second message, the quotation is from Smith. The two-group comparison is my own idea.

   What you do not say stays unknown.

4. Have it read for anything private.

   Say to your agent

   Read every file of the draft for private or third-party material and redact it.

5. Finalize it.

   Say to your agent

   I have read the draft. Finalize it in my name, Your Name, then commit.

   Your agent runs the record’s routine in one command: it brings the record up to date, screens it, records the disclosure review, moves it to ai/records/, checks it and drafts the commit body from it, with the record’s name and the execution marker. If something is missing, such as a check or a turn the summary does not cite, it says what and moves nothing; your agent adds it and runs the command again.

What a draft looks like

From the example project, the four parts you read before you finalize:

1 Your words, verbatim

evidence.json · T1 Miros Zohrehvand

Work out the share of non-publication cases in each filing year from workspace/sandbox/filings.csv, and the overall share as total cases over total patents. Put the result in workspace/sandbox/shares.md and tell me what you checked.

2 What the agent did

summary.md

Computed each year's share from its counts, and the overall share as 239 / 2166 = 11.0%.

3 What it checked

checks.jsonl · claude-opus-5-5 (model, advisory)

summed the five rows and recomputed each share from its counts: totals 239 cases and 2166 patents; every share matches.

4 What it did not check

checks.jsonl · limits

The counts were not checked against the original filing records.

A real draft record from an example project: what you read before saying finalize.

Things to know

• Your words are the evidence. A summary or commit body never replaces what you said.
• You are the default owner of what you directed. When the agent selects an approach on its own, the record says it was the agent’s selection.
• One record for the whole session. A later commit of the same session updates the same record: no turn is renumbered, and a choice or check already in it is not rewritten.
• A choice states its reason. The reason is why the choice was taken over the alternatives, not the direction it answers. A choice recorded without one reads not stated, and nothing is refused for it.
• The privacy review is not acceptance. It does not accept the work or permit sharing the record elsewhere. The routine clears it only when the agent declares it has read every captured turn and the local screen finds nothing.
• Nothing stops a commit. When your agent finds no transcript of its session, it commits with a body that says no record was kept and why.

What the agent runs

python3 scripts/trace_record.py session                     # this session's transcript, and the model that executes it
python3 scripts/trace_record.py decision <record> --input <json> --scope "..."   # a choice, with its reason, when it is made
python3 scripts/trace_record.py annotate-input workspace/record-staging/<session> \
    --input workspace/record-staging/annotation.json --by <actual-agent-or-person>
python3 scripts/trace_record.py keep --subject "<the commit's subject>"   # before each commit: the whole routine
python3 scripts/trace_record.py keep --subject "<the commit's subject>" \
    --cleared <digest>                                      # after reading every captured turn, with the digest keep printed
python3 scripts/trace_record.py keep --exclude <turn> "<reason>"   # exclude a turn the summary does not cite, with the reason
git commit --file <the body keep drafted>

The routine’s steps stay available on their own:

python3 scripts/trace_record.py extract --help              # the extractor's arguments; extract current reads the running session
python3 scripts/trace_record.py extract --help              # run it again into the same staging folder for a later turn
python3 scripts/trace_record.py cover workspace/record-staging/<session>
python3 scripts/trace_record.py privacy-check workspace/record-staging/<session>
python3 scripts/trace_record.py publication-review workspace/record-staging/<session> \
    --by <actual-reviewer> --scope "Intended repository audience and sharing context"
python3 scripts/trace_record.py promote workspace/record-staging/<session> ai/records/<session>
python3 scripts/trace_record.py verify ai/records/<session> --strict
python3 scripts/trace_record.py draft-message <record> --subject "..." --out <file>
git commit --file <file>