outl rust.instructions.md

Rust quality bar

Comment when the diff introduces any of the following. Skip when the existing surrounding code already does it (that's a separate cleanup).

• .unwrap() outside #[cfg(test)] — require .expect("explicit reason") or ? propagation. The expect message must name the invariant being asserted, not just "should not fail".
• .unwrap_or_default() masking an error path — if the default is a silent data-loss bug, flag it.
• unsafe in outl-core without a // SAFETY: comment naming the invariants the caller relies on.
• anyhow in a library crate (outl-core, outl-md, outl-actions). Libraries use thiserror so callers can match on variants. anyhow is only OK at binary boundaries (outl-cli, outl-tui).
• Box<dyn Error> as a public return type — same reason.
• String where &str works, Vec<T> where &[T] works, owned arg where borrowed works — but only in public APIs and hot paths; do not bikeshed this on internal helpers.
• async fn with a blocking call inside (std::fs, std::thread::sleep, large CPU loop without spawn_blocking).
• Holding a Mutex/RwLock across an .await — deadlock waiting to happen.
• Public API change on outl-core, outl-md, or outl-actions without doc-comment update — the per-crate CLAUDE.md should also reflect it.

Skip these (CI / fmt / clippy handle them):

• Import ordering, line width, brace placement.
• Naming conventions clippy already lints.
• mod declaration order.

---

Performance — hot paths only

Comment on performance only when the code is on a path that runs frequently or scales with workspace size. Do not flag allocations in setup, error paths, or one-shot CLI commands.

Paths that are hot in outl:

• outl_core::tree — every op apply, every materialized-tree walk.
• outl_core::log — every append, every replay (workspace boot, sync pull).
• outl_md::parse / outl_md::render — every .md read/write, every TUI refresh of a buffer.
• outl_md::index — backlink index rebuild scales with workspace size.
• outl_tui render loop — runs on every keystroke.
• outl_actions::SyncEngine work loop — runs on every file event.