init repo

docs/ai/bevy-debug-playbook.md

@@ -0,0 +1,62 @@
+# Bevy Debug Playbook
+
+## When build fails
+
+Run:
+
+```bash
+cargo check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Quote exact compiler error. Fix smallest cause first.
+
+## When game opens but nothing visible
+
+Check:
+
+1. camera spawned?
+2. entity has render component?
+3. transform in view?
+4. asset path correct?
+5. window created?
+6. alpha / color not invisible?
+7. system registered in right schedule/state?
+
+## When movement broken
+
+Check:
+
+- input system runs?
+- query matches entity?
+- transform or velocity changed?
+- another system overwrites transform?
+- delta time used correctly?
+
+## When UI broken
+
+Check:
+
+- UI entity spawned?
+- text component updated?
+- wrong state schedule?
+- score resource/event exists?
+- UI and gameplay mixed too tightly?
+
+## When architecture feels messy
+
+Refactor by:
+- extracting plugin
+- moving singleton data into resource
+- replacing direct calls with events
+- introducing state for flow
+- shrinking system queries
+
+## Review output format for AI
+
+When AI reviews code, demand:
+
+1. top 3 bugs
+2. top 3 architecture risks
+3. concrete patch plan
+4. exact commands to verify