diff --git a/crates/skate-game/src/retail_shader_tests.rs b/crates/skate-game/src/retail_shader_tests.rs
index ef19e33c..8bbfd053 100644
--- a/crates/skate-game/src/retail_shader_tests.rs
+++ b/crates/skate-game/src/retail_shader_tests.rs
@@ -18,6 +18,9 @@ use std::collections::HashMap;
 fn validate(source: &str, extras: &[&str]) -> naga::Module {
     let mut defs = HashMap::from([("MATERIAL_BIND_GROUP".into(), ShaderDefValue::UInt(3))]);
     for &name in [
+        // Bevy's mesh pipeline sets this for every mesh with positions
+        // (bevy_pbr mesh.rs); forward_io's Vertex only declares it then.
+        "VERTEX_POSITIONS",
         "VERTEX_UVS_A",
         "VERTEX_UVS_B",
         "VERTEX_TANGENTS",
diff --git a/docs/hails-additions/10-sky-shader-test.md b/docs/hails-additions/10-sky-shader-test.md
new file mode 100644
index 00000000..037eb8bf
--- /dev/null
+++ b/docs/hails-additions/10-sky-shader-test.md
@@ -0,0 +1,45 @@
+# Sky shader validation test
+
+Branch: `gameplay/water`. Status: **done**; test-only change, no game behaviour changes.
+
+## Problem
+
+`retail_render::shader_tests::sky_shader_validates` failed on untouched upstream
+(`60efdef`) and was listed as a known pre-existing failure:
+
+```
+error: invalid field accessor `position`
+29 │     let world = v.position + vec3<f32>(view.world_position.x, ...
+```
+
+## Root cause
+
+`retail_sky.wgsl` takes `bevy_pbr::forward_io::Vertex`, whose `position` field is
+declared only under `#ifdef VERTEX_POSITIONS`
+(`vendor/bevy_pbr/src/render/forward_io.wgsl`). Bevy's mesh pipeline pushes
+`VERTEX_POSITIONS` for every mesh layout that has positions
+(`vendor/bevy_pbr/src/render/mesh.rs`, `shader_defs.push("VERTEX_POSITIONS")`), so
+the shader compiles in the game. The test's `validate` helper
+(`crates/skate-game/src/retail_shader_tests.rs`) composes shaders with its own
+def list, which included the UV/tangent/colour/normal defs but not
+`VERTEX_POSITIONS`. The world shader never reads `Vertex.position`, so only the
+sky test tripped over it.
+
+## Change
+
+Add `VERTEX_POSITIONS` to the shader defs in `validate`, matching what Bevy sets
+for real meshes. The shader is unchanged.
+
+## Files
+
+- `crates/skate-game/src/retail_shader_tests.rs`
+
+## Verification
+
+`cargo test --locked -p skate-game --release --bin skate3rust -- shader_tests`:
+all six pass (`sky_shader_validates`, world, depth in every shadow configuration,
+character, and both vertex-location checks).
+
+## Open questions
+
+None. The PR plan's list of known upstream failures notes this one as fixed.