add "fix causes, not symptoms" to review and contributor guidelines

CLAUDE.md

@@ -101,6 +101,14 @@ The handwritten notes are prepended above the auto-generated changelog and are t
 - Minor fixes: keep body short and concise
 - No "test plan" sections or testing summaries
 
+### Code Review Guidelines
+
+- **Fix causes, not symptoms.** When a PR works around a problem instead of addressing why it occurs, that's a red flag. A side-channel that compensates for a missing step adds permanent complexity. If the fix doesn't change the code path where the bug actually happens, ask why not.
+- Focus on API design and naming clarity
+- Identify confusing patterns (e.g., parameter values that contradict defaults) or non-idiomatic code (mutable defaults, etc.). Contributed code will need to be maintained indefinitely, and by someone other than the author (unless the author is a maintainer).
+- Suggest specific improvements, not generic "add more tests" comments
+- Think about API ergonomics from a user perspective
+
 ### Code Standards
 
 - Python ≥ 3.10 with full type annotations

CONTRIBUTING.md

@@ -36,6 +36,7 @@ If you do open a PR:
 - **Keep it focused.** One logical change per PR. Don't bundle unrelated fixes or refactors.
 - **Match existing patterns.** Follow the code style, type annotation conventions, and test patterns you see in the codebase. Run `uv run prek run --all-files` before submitting.
 - **Write tests.** Bug fixes should include a test that fails without the fix. Enhancements should include tests for the new behavior.
+- **Fix the cause, not the symptom.** If the bug is that a code path skips a step, the fix should make it stop skipping that step — not add compensation elsewhere. Workaround-style fixes will be sent back for revision.
 - **Don't submit generated boilerplate.** We review every line. PRs that read like unedited LLM output — verbose descriptions, speculative changes, shotgun-style fixes — will be closed.
 
 ## What we'll close without review