M03 Mutability
Resolve Rust borrow and mutability errors (E0596, E0499, E0502) by choosing the right mutability design instead of patch fixes.
Overview
m03-mutability is an agent skill for the Build phase that guides Rust mutability and interior-mutability choices when borrow checker errors block compilation.
Install
npx skills add https://github.com/zhanghandong/rust-skills --skill m03-mutabilityWhat is this skill?
- Maps compiler errors E0596, E0499, E0502, and RefCell panics to design questions—not quick fixes
- Decision flow: necessary mutation, who controls it, and single- vs multi-thread context
- Covers &mut T, Cell/RefCell, Mutex/RwLock, and atomic patterns
- Layer 1 language-mechanics framing with trace-up guidance when borrow conflicts persist
- Triggers on cannot borrow as mutable, interior mutability, and related Chinese keywords in errors
- Maps 4+ named error patterns (E0596, E0499, E0502, RefCell panic) to design questions
Adoption & trust: 730 installs on skills.sh; 1.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Rust code fails with E0596, E0499, or E0502 and repeated local fixes keep reintroducing borrow conflicts.
Who is it for?
Indie builders shipping Rust APIs, CLIs, or agents who hit borrow errors and need structured reasoning before RefCell or Mutex.
Skip if: Greenfield Rust learners who have not yet read ownership basics, or pure frontend/JavaScript stacks with no Rust crate.
When should I use this skill?
CRITICAL for mutability issues: E0596, E0499, E0502, cannot borrow as mutable, interior mutability, Cell, RefCell, Mutex, RwLock.
What do I get? / Deliverables
You choose a coherent mutability model—shared vs exclusive, interior vs synchronized—that compiles and matches who should change the data.
- Mutability strategy recommendation aligned to thread context
- Reframed data-structure approach when split borrows are symptomatic
Recommended Skills
Journey fit
Borrow and mutability design is core implementation work while writing or refactoring Rust services and CLIs. Backend and systems Rust code is where ownership, interior mutability, and concurrent locks most often block compilation.
How it compares
Use as a compile-error design coach, not a generic Rust tutorial or cargo scaffolding generator.
Common Questions / FAQ
Who is m03-mutability for?
Solo developers implementing Rust backends or tools who need the agent to interpret borrow-checker errors and suggest structural mutability fixes.
When should I use m03-mutability?
During Build while writing or refactoring Rust modules when errors mention mutable borrows, already borrowed, interior mutability, Cell, RefCell, Mutex, or RwLock.
Is m03-mutability safe to install?
It is documentation-only guidance with no mandated shell or network use—confirm package integrity via the Security Audits panel on this Prism page.
SKILL.md
READMESKILL.md - M03 Mutability
# Mutability > **Layer 1: Language Mechanics** ## Core Question **Why does this data need to change, and who can change it?** Before adding interior mutability, understand: - Is mutation essential or accidental complexity? - Who should control mutation? - Is the mutation pattern safe? --- ## Error → Design Question | Error | Don't Just Say | Ask Instead | |-------|----------------|-------------| | E0596 | "Add mut" | Should this really be mutable? | | E0499 | "Split borrows" | Is the data structure right? | | E0502 | "Separate scopes" | Why do we need both borrows? | | RefCell panic | "Use try_borrow" | Is runtime check appropriate? | --- ## Thinking Prompt Before adding mutability: 1. **Is mutation necessary?** - Maybe transform → return new value - Maybe builder → construct immutably 2. **Who controls mutation?** - External caller → `&mut T` - Internal logic → interior mutability - Concurrent access → synchronized mutability 3. **What's the thread context?** - Single-thread → Cell/RefCell - Multi-thread → Mutex/RwLock/Atomic --- ## Trace Up ↑ When mutability conflicts persist: ``` E0499/E0502 (borrow conflicts) ↑ Ask: Is the data structure designed correctly? ↑ Check: m09-domain (should data be split?) ↑ Check: m07-concurrency (is async involved?) ``` | Persistent Error | Trace To | Question | |-----------------|----------|----------| | Repeated borrow conflicts | m09-domain | Should data be restructured? | | RefCell in async | m07-concurrency | Is Send/Sync needed? | | Mutex deadlocks | m07-concurrency | Is the lock design right? | --- ## Trace Down ↓ From design to implementation: ``` "Need mutable access from &self" ↓ T: Copy → Cell<T> ↓ T: !Copy → RefCell<T> "Need thread-safe mutation" ↓ Simple counters → AtomicXxx ↓ Complex data → Mutex<T> or RwLock<T> "Need shared mutable state" ↓ Single-thread: Rc<RefCell<T>> ↓ Multi-thread: Arc<Mutex<T>> ``` --- ## Borrow Rules ``` At any time, you can have EITHER: ├─ Multiple &T (immutable borrows) └─ OR one &mut T (mutable borrow) Never both simultaneously. ``` ## Quick Reference | Pattern | Thread-Safe | Runtime Cost | Use When | |---------|-------------|--------------|----------| | `&mut T` | N/A | Zero | Exclusive mutable access | | `Cell<T>` | No | Zero | Copy types, no refs needed | | `RefCell<T>` | No | Runtime check | Non-Copy, need runtime borrow | | `Mutex<T>` | Yes | Lock contention | Thread-safe mutation | | `RwLock<T>` | Yes | Lock contention | Many readers, few writers | | `Atomic*` | Yes | Minimal | Simple types (bool, usize) | ## Error Code Reference | Error | Cause | Quick Fix | |-------|-------|-----------| | E0596 | Borrowing immutable as mutable | Add `mut` or redesign | | E0499 | Multiple mutable borrows | Restructure code flow | | E0502 | &mut while & exists | Separate borrow scopes | --- ## Interior Mutability Decision | Scenario | Choose | |----------|--------| | T: Copy, single-thread | `Cell<T>` | | T: !Copy, single-thread | `RefCell<T>` | | T: Copy, multi-thread | `AtomicXxx` | | T: !Copy, multi-thread | `Mutex<T>` or `RwLock<T>` | | Read-heavy, multi-thread | `RwLock<T>` | | Simple flags/counters | `AtomicBool`, `AtomicUsize` | --- ## Anti-Patterns | Anti-Pattern | Why Bad | Better | |--------------|---------|--------| | RefCell everywhere | Runtime panics | Clear ownership design | | Mutex for single-thread | Unnecessary overhead | RefCell | | Ignore RefCell panic | Hard to debug | Handle or restructure | | Lock inside hot loop | Performance killer | Batch operations | --- ## Related Skills | When | See | |------|-----| | Smart pointer choice | m02-resource | | Thread safety | m07-concurrency