--- title: "Recording a content pipeline" slug: /workflows/content-pipeline/ markdown: /workflows/content-pipeline.md section: project-setup tier: 1 summary: "Record the build procedure for a category of content so the next instance is made identically." sources: ['pipeline-blueprint.md'] canonical: https://unityworkflowlibrary.dev/workflows/content-pipeline/ read_first: /read-first.md --- > Read first, on every prompt: [non-destructive rules](/read-first.md). # Recording a content pipeline > Record the build procedure for a category of content so the next instance is made identically. 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: PRODUCES: INPUTS: INVARIANTS: STAGES: GATE PER STAGE: FOLD POINTS: SUBDIVIDE AT: IDEMPOTENCE: ONE-SHOT TEST: ``` - **PRODUCES is a path shape, not a description.** `Scenes/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/.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: ` 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/.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](/workflows/new-unity-project/) page). The pipeline document is **architecture** — the comment budget in the [C# style](/workflows/csharp-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.