# 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