Pitfalls: import pipelines & evidence

Generalized pitfalls from asset-import and extraction pipelines in active projects. Record your own project's traps the same way: Keeping a project pitfall file. All entries LOCKED evidence. Status: locked (empirical, seen in shipped/active projects).

• A-NEGATIVE-NEEDS-TWO-SOURCES — before declaring content absent, confirm with two independent sources. Check: absence claims cite a full-index search and a second method. Status: locked (empirical, seen in shipped/active projects).

• PARSE-FAILURE-LOOKS-LIKE-ABSENCE — assume a parser failed before concluding data is missing. Check: assert parsed counts against the source's own declared counts; make deserialization failures fatal. Status: locked (empirical, seen in shipped/active projects).

• A-GATE-THAT-CANNOT-FAIL-IS-NOT-A-GATE — checks like "properties > 0" pass on partial/broken output. Check: gates compare against an independent oracle (expected count, known values). Status: locked (empirical, seen in shipped/active projects).
• PER-ITEM-GUARDS-HIDE-SYSTEMIC-FAILURE — a try/catch per item turns "everything failed" into silence. Check: count per-item failures and fail the batch above a threshold. Status: locked (empirical, seen in shipped/active projects).
• FIX-PASSES-MUST-UNDO-THEIR-OWN-OUTPUT — an additive binder can never remove a wrong bind it made earlier. Check: fix passes recompute from source and clear prior generated output. Status: locked (empirical, seen in shipped/active projects).
• RESUMABLE-JOBS-WRITE-PROGRESS-FIRST — write the progress marker atomically with (or before) the records it covers. Status: locked (empirical, seen in shipped/active projects).

• ZERO-TRANSFORMS-ARE-PADDING — a location of exactly (0,0,0) in imported placement data is a defaulted value, not a placement. Check: sweep the whole manifest for zero transforms and refuse them at import. Status: locked (empirical, seen in shipped/active projects).

• A-MISSING-MAP-STILL-RENDERS — dropped normal/roughness maps fail silently; the tell is a ratio (textures exported vs bound). Check: report bound/available ratios per map type after import. Status: locked (empirical, seen in shipped/active projects).
• VERIFY-TEXTURE-PACKING-FROM-PIXELS — channel packing must be verified from pixel statistics, never from suffixes or parameter names. Check: channel-correlation test (real albedo is strongly correlated RGB). Status: locked (empirical, seen in shipped/active projects).

• FLAT-NORMALS-ARE-WORSE-THAN-NONE — binding an identity/flat normal makes a material report "has normal" while adding nothing. Check: exclude placeholder normals from coverage metrics. Status: locked (empirical, seen in shipped/active projects).
• EMISSIVE-MAPS-NEED-AN-EMISSIVE-COLOR — a bound emissive map multiplied by a default black emissive color emits nothing. Check: set emissive color/intensity when binding emissive maps. Status: locked (empirical, seen in shipped/active projects).
• BAKED-BOUNDS-OFFSET-VS-PIVOT — analyse imported meshes at their bounds centre but instantiate at the pivot. Status: locked (empirical, seen in shipped/active projects).

• ORIENTATION-IS-MEASURED-NOT-EYEBALLED — a wrong axis mapping can still score high visual overlap. Check: verify coordinate conversion with asymmetric reference points. Status: locked (empirical, seen in shipped/active projects).
• CRLF-POISONS-PATH-LISTS — lists written on Windows carry a trailing carriage return that makes every lookup miss. Check: strip line endings when reading path lists. See also PERL-MULTILINE-MISSES-CRLF. Status: locked (empirical, seen in shipped/active projects).
• DEV-PLACEHOLDERS-SHIP — retail content contains test/placeholder assets. Check: filter by explicit placeholder paths/materials during import. Status: locked (empirical, seen in shipped/active projects).