Code Quality

Right:

// If only one branch should ever be hit:
assert!(condition, "invariant violated: ...");
// OR
return Err(LimboError::InternalError("unexpected state".into()));
// OR
unreachable!("impossible state: ...");

Use if-statements only when both branches are expected paths.

Comments

Do:

• Document WHY, not what
• Document functions, structs, enums, variants
• Focus on why something is necessary

Don't:

• Comments that repeat code
• References to AI conversations ("This test should trigger the bug")
• Temporal markers ("added", "existing code", "Phase 1")

Avoid Over-Engineering

• Only changes directly requested or clearly necessary
• Don't add features beyond what's asked
• Don't add docstrings/comments to unchanged code
• Don't add error handling for impossible scenarios
• Don't create abstractions for one-time operations
• Three similar lines > premature abstraction

Index Mutations

When code involves index inserts, deletes, or conflict resolution, double-check the ordering against SQLite. Wrong ordering causes index inconsistencies. and easy to miss.

Ensure understanding of IO model

• Async IO model

Cleanup

• Delete unused code completely
• No backwards-compat hacks (renamed _vars, re-exports, // removed comments)