Commit the Tool, Discard the Render

Almost Nothing Survives a Run

A finished episode leaves behind a working directory full of substantial artifacts: the fetched material, the brief, the script, dozens of image plates, dozens of audio takes, video clips, the final render, and a long log of every judgment made along the way. None of it is committed. The repository gains, at most, one line in an index file.

The reasoning is a single sentence: the episode is reproducible from the tool plus the pointer. The material already lives properly in the system that owns it. The tool is versioned. So everything in between is derived, and derived things do not need to be stored — they need to be rebuildable.

The Uncomfortable Part

Here is where this design says something most engineers would flinch at. Re-running the pipeline on the same pointer does not produce a byte-identical video. Speech synthesis is not deterministic; generated art is not deterministic. The second render would be a slightly different film.

And the doctrine's response is that this is a feature, not drift — the variation is treated as acceptable rather than as a defect to engineer away. That is a genuinely unusual position and it is worth understanding rather than copying blindly. It works because of what reproducibility is for here. Nobody needs to prove this exact file was produced by that exact code; there is no audit requirement, no regulatory replay, no bug that will be diagnosed by diffing two renders. What people actually need is the ability to make the episode again if the file is lost, and a slightly different take satisfies that completely.

Change the purpose and the answer changes with it. If a render were evidence, or a build artifact other things depended on, or something a customer had paid for a specific version of, then non-determinism would be unacceptable and every generated asset would need to be pinned. The lesson is to ask what your reproducibility is actually protecting against before paying for the strong version of it.

Store what cannot be regenerated. The line is not "big files are bad" — it is whether the artifact carries information that exists nowhere else. Source material, decisions, and judgments carry such information. Renders, builds, and caches do not; they are functions of things you already have, and keeping them is paying storage and review cost for a value you can recompute.

Code

Three homes, three lifetimes·text

the repository      = the TOOL          git-tracked, permanent
  pipeline.py, FORMAT.md, EPISODES.md

the owning system   = the MATERIAL      stored properly, already
  conversations, journals, essays - fetched fresh at run time

the working dir     = the OUTPUT        never committed, disposable
  brief, script, plates, takes, clips, render, run log

# reproducible = TOOL + POINTER
# not: reproducible = an archive of everything that ever happened

What "rebuildable" means in practice·bash

# the render was deleted, the disk died, the directory was cleaned.
# recovery is not a restore - it is a re-run.

pipeline.py all --conversation <pointer-id>

# what comes back:
#   the same argument, the same structure, the same script
#   a slightly different set of speech takes
#   slightly different generated art
#
# accepted deliberately. the thing being preserved is the ABILITY
# to make the episode, not a particular sequence of bytes.

Exercise

Look at what your repositories currently store that is generated: compiled output, lock files, fixtures, snapshots, exported data. Sort each into "carries information that exists nowhere else" or "a function of things already committed." For anything in the second group, write down why it is stored — and whether that reason is reproducibility, convenience, or that nobody has dared remove it.

Hint

Lock files are the interesting boundary case and worth thinking through rather than pattern-matching: they are derived from a manifest, but they pin a resolution that the manifest alone would not reproduce, which means they carry information that genuinely exists nowhere else.

Almost Nothing Survives a Run

The Uncomfortable Part

Code

External links

Exercise

Progress

Comments 0