1 files changed, 22 insertions, 41 deletions
diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md
index 3a09dbc..de6378a 100644
--- a/doc/CONTRIBUTING.md
+++ b/doc/CONTRIBUTING.md
@@ -1,5 +1,7 @@
 # Contributing Guidelines
 
+---
+
 ## Commit Policy
 
 ### Verify Before Committing
@@ -8,7 +10,6 @@
 ```bash
 ./scripts/check_all.sh
 ```
-Runs tests, builds tools, cross-compiles Windows.
 
 **Manual:**
 ```bash
@@ -26,18 +27,9 @@ cd build && ctest --output-on-failure
 cmake -S . -B build_debug_check -DDEMO_ENABLE_DEBUG_LOGS=ON
 cmake --build build_debug_check -j4
 ```
-Must compile without errors.
 
 **Debug macros** (`src/util/debug.h`):
-- `DEBUG_LOG_AUDIO`, `DEBUG_LOG_RING_BUFFER`, `DEBUG_LOG_TRACKER`
-- `DEBUG_LOG_SYNTH`, `DEBUG_LOG_3D`, `DEBUG_LOG_ASSETS`, `DEBUG_LOG_GPU`
-
-Example:
-```cpp
-#if defined(DEBUG_LOG_AUDIO)
-  DEBUG_AUDIO("[CALLBACK #%d] frames=%d\n", ++count, frames);
-#endif
-```
+- `DEBUG_LOG_AUDIO`, `DEBUG_LOG_RING_BUFFER`, `DEBUG_LOG_TRACKER`, `DEBUG_LOG_SYNTH`, `DEBUG_LOG_3D`, `DEBUG_LOG_ASSETS`, `DEBUG_LOG_GPU`
 
 ### Code Formatting
 ```bash
@@ -50,6 +42,8 @@ Never format `third_party/`.
 - 3-line header comment
 - Max 500 lines (split if larger)
 
+---
+
 ## Coding Style
 
 ### Core Rules
@@ -61,36 +55,9 @@ Never format `third_party/`.
 - No `auto` (except complex iterators)
 - No C++ casts (`static_cast`, `reinterpret_cast`)
 
-### Preprocessor
-```cpp
-#if defined(MY_TAG)
-  ...
-#endif /* defined(MY_TAG) */
-```
+See `doc/CODING_STYLE.md` for detailed examples.
 
-### Struct Initialization
-```cpp
-// Good
-const WGPUDescriptor desc = {
-  .format = g_format,
-  .dimension = WGPUTextureViewDimension_2D,
-};
-
-// Bad
-WGPUDescriptor desc = {};
-desc.format = g_format;
-desc.dimension = WGPUTextureViewDimension_2D;
-```
-
-### Class Keywords
-```cpp
- private:  // 1 space indent
-  int field_;
-```
-
-### Comments
-- 1-line comment for non-obvious functions
-- 3-line header for all source files
+---
 
 ## Development Protocols
 
@@ -170,4 +137,18 @@ After hierarchy changes (moving files, renaming), verify:
 ./scripts/gen_coverage_report.sh
 ```
 
-Update scripts with hardcoded paths.
+---
+
+## Uniform Buffer Checklist
+
+To ensure consistency and prevent alignment-related issues:
+
+1. **Define WGSL Structs:** Pay attention to type alignment (`f32`, `vec2`, `vec3`, `vec4`) and use explicit padding where necessary.
+2. **Mirror in C++:** Create corresponding C++ structs that mirror WGSL definitions.
+3. **`static_assert` for Size:** Every C++ struct must have a `static_assert` verifying size matches WGSL.
+4. **Standard Bindings:**
+   - **Binding 2:** Always use `CommonPostProcessUniforms` for per-frame data (resolution, time, beat).
+   - **Binding 3:** Use effect-specific parameter structs for unique data.
+5. **Shader Consistency:** Ensure WGSL shaders correctly declare uniforms at specified bindings.
+6. **Validation Script:** Run `tools/validate_uniforms.py` to catch discrepancies.
+7. **Documentation:** Refer to `doc/UNIFORM_BUFFER_GUIDELINES.md` for detailed alignment rules.