Recording a content pipeline · Unity Workflow Library

the system blueprint page prescribes the shape of ONE system. This file prescribes the shape of a repeatable build — the ordered procedure that turns authored inputs into a working instance of a category, written down while the first instance is being built, so the second is a prompt and not an excavation.

When a pipeline is required

Write one the FIRST time you build something that will exist more than once:

A category with plural instances — a world, a level, a biome, a faction, a weapon class, a vehicle, a boss, a quest chain, a localisation, a platform target.
Any build that crossed three or more owners (an asset, a scene, a definition, code, a bake).
Any procedure you reconstructed by reading code because nobody wrote it down. Recording it is the fix; the next agent must not repeat the excavation.

A one-off with no second instance does not get a pipeline. A category does, before the first instance ships — writing it after the fact means writing it from the artefact instead of from the decisions, and the decisions are the part that does not survive.

The declaration (write it BEFORE building the first instance)

PIPELINE:      <the category, plural: "a planet", "a faction">
PRODUCES:      <the exact artefact list one run creates, by path shape>
INPUTS:        <every authored value a run needs, with its owner and its units>
INVARIANTS:    <what must be true of any instance, as checkable assertions>
STAGES:        <ordered; each one named, with its own gate>
GATE PER STAGE:<the check that proves that stage produced a correct artefact>
FOLD POINTS:   <stages that collapse into one when the instance is simple>
SUBDIVIDE AT:  <the signal that a stage must split, and into what>
IDEMPOTENCE:   <what a re-run overwrites, what it must never touch>
ONE-SHOT TEST: <the prompt that rebuilds an instance from nothing, verbatim>

PRODUCES is a path shape, not a description. Scenes/<id>Surface.unity, not "a surface scene". The next agent globs it; prose cannot be globbed.
INPUTS carries units and owner. A number with no unit is a defect that ships. A number with no owner gets authored twice in two places, which is the same defect a year later.
INVARIANTS are assertions, not intentions. "Period must satisfy T² = 4π²a³/GM to 0.5%" is an invariant; "orbits should be realistic" is a wish. Every invariant is callable from a test.
Every stage has its own gate. A pipeline whose only check is at the end tells you something broke, not where. The gate is what makes a stage foldable — you can only merge two stages safely when you can still prove each one's output.
IDEMPOTENCE is the line between "re-run" and "destroy the developer's work." State explicitly which artefacts a re-run regenerates and which are hand-authored and off limits. A pipeline that cannot say this will eventually be run over live content.
ONE-SHOT TEST is the acceptance criterion for the pipeline itself. If you cannot write the prompt that rebuilds an instance, the pipeline is not recorded yet — it is still in your head, and your head is not a deliverable.

Fold and subdivide

A pipeline is not a fixed number of steps; it is a tree with a stated resolution.

FOLD when an instance does not use a stage's degrees of freedom: two stages that always run together with no decision between them are one stage. Record the fold, do not delete the stage — the next instance may need it back, and a deleted stage is rediscovered by excavation.
SUBDIVIDE when a stage acquires its own failure modes, its own gate, or a second owner. The signal is a stage whose gate has started asking two unrelated questions. Split it and give each half its own gate in the same change.
Depth is stated per instance, not per pipeline. The document holds the full tree; an instance records which stages it folded and why. Two instances at different depths are normal; two instances that folded differently with no recorded reason are drift.

Recording the first build

The first instance is the reference. While building it:

Write each stage as you finish it, not at the end. A stage written from memory loses the decisions and keeps only the result, and the decisions are what make the second instance cheap.
Record what you rejected and why. The next agent will reach for the same rejected approach unless the pipeline says it was tried. One line per rejection.
Record the measured numbers, not the intended ones. What the value ended up being, and what measurement chose it. An authored constant with no recorded measurement is re-tuned from scratch every time somebody doubts it.
Name the gate that caught each mistake. A stage gate that caught nothing during the first build is probably not a gate.

Every later instance feeds the pipeline (PIPELINE-GROWS-WITH-EVERY-INSTANCE, HARD)

Record what worked so the next instance avoids the same setup pitfalls, keep that record updated as part of the work, and flag the steps likely to apply in similar Unity situations.

Whoever uses the pipeline writes it. Any agent building, extending or repairing an instance of a category with a docs/pipelines/ file updates that file as part of its own work, unasked.
When: in the commit where a stage worked, failed or cost a retry; at every handoff or pause; at the finish. A handoff whose pitfalls live only in the task record or chat is incomplete.
What, per stage: the step that worked (tool action, recipe path, command), the measured numbers, and pitfalls as symptom -> cause -> fix or check, naming the gate that caught it (none caught it = add a gate). Plus progress: which stages this instance passed, so the next agent resumes.
Fold, never diary. Put each finding into the stage it belongs to, so a fresh agent can still follow the file top to bottom. Dated narrative goes to the task record.
Tag each pitfall [general] or [project]. General = true in any Unity project using the same engine feature (import, prefab, colliders, layers, baking, lighting, animation, UI). Promote each [general] one into its spoke per the global promote page in the same session, and leave a one-line pointer to that rule id in the pipeline.
Before starting an instance, read the pipeline's pitfalls and the spokes they point to. The second instance is only faster if the first one's mistakes are read first.

Every pitfall is saved, pipeline or not (EVERY-PITFALL-IS-SAVED, HARD)

Measured the same day: of 28 pipeline files in one project, 8 carried any tagged pitfall; the other 20 had none, and the lessons lived in private agent memory, task records and chat, where no other project and no fresh agent reads them.

Scope is every finding, not every pipeline. A bug fix, a crash, a wrong measurement, a tool that lied, a merge that lost work: each is a pitfall. PIPELINE-GROWS-WITH-EVERY-INSTANCE covers categories that have a pipeline; this rule covers the rest.
Where: the category's docs/pipelines/<CATEGORY>.md (create it with just a Pitfalls section when the category has none), else the project's pitfall index (docs/pipelines/PITFALLS.md), grouped by category so an agent finds it by the thing it is touching, never by date.
Shape: [general] or [project], then symptom -> cause -> fix or check, the gate that caught it (none = add one), and the commit or record that proved it. One line to four, no diary.
When: in the commit that learned it. A fix commit without its pitfall line is incomplete.
Promote: each [general] pitfall lands in its spoke per the global promote page in the same session; the project line keeps a pointer to the rule id.
Agent memory is not storage. A general lesson written to a per-machine memory note is promoted too; memory may point at the rule, it never replaces it.
Handoff line: every handoff and done record states pitfalls saved: N, promoted: <ids> or none found. A lane that fixed a defect and saved nothing reports a gap, not a pass.
Backfill is owed. A pipeline file with no tagged pitfall is debt: the next agent in that category mines its task records, fix commits and memory notes for the pitfalls already paid for.

Where it lives

Project docs, one file per category: docs/pipelines/<CATEGORY>.md. Link it from the project's agent instructions index so it is found by routing, not by search. Edit only the project's own agent files; a global agent instructions file outside the project is changed only with ASK-BEFORE-EDITING-OUTSIDE-THE-PROJECT (on the Project setup page). The pipeline document is architecture — the comment budget in the C# style page sends facts of this size here rather than into a doc comment, and code that implements a stage carries a one-line pointer to it.

A pipeline document that has drifted from the code is worse than none, exactly like a stale graph: it is trusted and wrong. When a stage changes, the document changes in the SAME commit as the code.