docs: add shader compilation troubleshooting entry

docs/TROUBLESHOOTING.md

@@ -123,6 +123,23 @@ Not this (which returns a solid color):
 return vec4<f32>(1.0, 1.0, 1.0, 1.0);  // wrong: solid white
 ```
 
+## 11. WGSL shader compilation errors
+
+**Symptom:** Program panics or logs errors during `device.create_shader_module()` or `create_render_pipeline()` with messages referencing WGSL validation failures.
+
+**Cause:** wgpu validates WGSL shaders at pipeline creation time, not at runtime. Errors surface immediately when the shader module is created or when the render pipeline references it. Common causes include:
+- Syntax errors: typos in WGSL (missing semicolons, mismatched braces, incorrect keywords)
+- Type mismatches: passing `vec2<f32>` where `vec4<f32>` is expected, or mixing signed/unsigned types
+- Missing `@location` or `@builtin` attributes: vertex/fragment shader I/O without proper decoration
+- Entry point not found: the `@vertex` or `@fragment` function name doesn't match the pipeline descriptor's `entry_point` field
+
+**Fix:** Read wgpu's error messages carefully — they include the shader source line and column where the issue was detected. Follow this checklist:
+- Check the reported line/column in your WGSL source for syntax issues
+- Verify all type signatures match between vertex shader output and fragment shader input
+- Ensure every varying uses `@location(N)` and position output uses `@builtin(position)`
+- Confirm the function name in your `@vertex`/`@fragment` declaration matches the string you pass to `ProgrammableStage::entry_point`
+- If the error message is unclear, try compiling the shader in isolation to isolate syntax vs. pipeline-binding issues
+
 ## Additional Resources
 
 - [Glossary](concepts/GLOSSARY.md) — Every term defined