A setup that leaves a paper trail

Most of my setup leaves a paper trail. I didn’t plan it that way. Over time I kept the bits that wrote things down and dropped the bits that didn’t, and now almost every step of a job ends up as a file I can go back and read.

The point isn’t documentation for its own sake. It’s so I can answer the boring questions later: why was this done, what was the original scope, what changed, what got parked.

What’s actually on disk

The trail is the artifacts left behind as work moves through. The task spec. The acceptance criteria. The draft a model produced. The review verdict. The merge commit. The final post.

All of it sits on disk where I can grep it. Nothing important lives only in a chat transcript.

The ordering is unremarkable. The thing that matters is that each arrow has a file attached.

Task files

Coding work gets written up as a task file before anything runs: objective, workspace, acceptance criteria, constraints, review level, branch. It looks formal for the size of some of these jobs, and I used to skip it for anything under about an hour. I’ve mostly stopped.

Not out of discipline. It’s that when the task file exists, the orchestrator has something real to read, and three days later when something fails, so do I. “Just tidy up the scaffolding” turns into a file with the actual criteria and the actual review notes. That’s the part I keep coming back to.

The cost is maybe five minutes. The payoff is that scope and definition of done are pinned down somewhere I can point at.

Review drafts

Writing has the same shape. I don’t draft a post straight into the canonical file. It gets written as a draft, a stronger model reads it against the brief, and the notes from that pass sit alongside the draft instead of being applied silently.

That sounds like overhead. In practice it makes the first version easier to write, because the draft is allowed to be bad and the review is allowed to be blunt. By the time the post lands, the decisions about scope and tone have happened somewhere written down.

If I skip the step, the same thinking still has to happen. It just ends up scattered across my head and a chat window, and I reconstruct it from memory later.

Notes

When I’m researching something, memory models, an inference setup, or a choice between two tools, what comes out is a note in the project’s notes folder. It’s not aimed at anyone. Sources, comparisons, tentative conclusions.

The value isn’t the conclusion. It’s that I didn’t have to carry the material in my head for a week. I could stop thinking about it, come back two days later, and read my own working.

When I try to hold a decision in my head instead, I either over-commit because I’ve forgotten the alternatives, or I redo the research because I’ve forgotten I already did it.

Why not just do it in chat

A lot of this could happen in a chat transcript. The model can plan, draft, and reason in one session, and that’s faster at the moment of doing it.

What I’ve had to admit is that faster-in-the-moment isn’t the variable I care about. I care about whether I can still explain the thing in three weeks. Chat is bad for that. Searching old transcripts is slow and the context gets fuzzier each time. A committed file with a title and a date is much easier.

The trail isn’t for someone auditing me. It’s for the version of me who comes back next week having forgotten the details.

Chat also encourages folding decisions and execution together. A file-based trail makes me separate them. The task file isn’t the code. The review isn’t the draft. Each has its own object.

What the objects look like

Nothing exotic. Task file is markdown with frontmatter. Output JSON is whatever the spawned pass writes. Review verdict is plain text. Note is a markdown file in a folder. Deliberately unglamorous, because glamorous formats go out of date and plain text doesn’t.

Where it costs

It’s not free.

Writing a task file for a ten-minute job feels silly, and sometimes it is. I’ve tried a few times to set a threshold below which I skip it, and I can’t make the threshold stick. When I skip it, the job expands and I wish I had the file, so I mostly just write it.

The trail also gets noisy. Lots of tasks, notes, draft versions. If I don’t prune, the folder becomes harder to search than my memory. I treat pruning as part of the work, but I’m not great at it.

And a paper trail isn’t the same as thinking clearly. It’s easy to mistake writing a task file for understanding the task. The file will happily record a confused plan. I’ve shipped a few.

Where it sits now

Task files for coding work. Drafts and review notes for writing. A notes folder per project for things that don’t belong in a task or a post. A merge commit tying it back to a diff.

It works better for me than the alternative because I can look backwards without guessing.