docs: add pre-commit checklist and common pitfalls to CLAUDE.md

Author: marloson

CLAUDE.md

@@ -109,3 +109,21 @@ Type-specific decoders invoked by the message formatter for custom Apple log obj
 ### Oversize String Handling
 
 A key complexity: some log entries reference oversize strings stored in different tracev3 files. The example binary demonstrates the pattern — accumulate oversize entries across files, then re-process any entries that had missing data in a second pass.
+
+## Pre-Commit Checklist
+
+Run these in order before every commit. All must pass:
+
+1. `cargo fmt -- --check` — formatting
+2. `cargo clippy -- -D warnings` — lints (zero warnings policy)
+3. `cargo test --release` — full test suite
+
+Or just run `/qa` from the repo root.
+
+## Common Pitfalls
+
+- **`#[deny(cast_lossless)]`** — Do not use `as` for widening casts (e.g., `u8 as u64`). Use `.into()` instead. Clippy will reject the PR otherwise.
+- **`#![forbid(unsafe_code)]`** — This is workspace-wide. No `unsafe` blocks anywhere, including new modules.
+- **Oversize entries span files** — A single log entry's oversize string may live in a different tracev3 file. Always accumulate oversize entries across all files before final log reconstruction. See `examples/` for the two-pass pattern.
+- **Test data is external** — Tests will fail without downloading test data first (`cd tests && wget ...`). Don't assume test failures mean code is broken until you verify test data exists.
+- **CI runs on macOS only** — x86_64 + aarch64. Linux builds work but CI doesn't test them.