m03-mutability
Debugs Rust mutability and interior mutability errors to ensure safe data access.
Install
mkdir -p .claude/skills/m03-mutability && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/5624" && unzip -o skill.zip -d .claude/skills/m03-mutability && rm skill.zipInstalls to .claude/skills/m03-mutability
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
CRITICAL: Use for mutability issues. Triggers: E0596, E0499, E0502, cannot borrow as mutable, already borrowed as immutable, mut, &mut, interior mutability, Cell, RefCell, Mutex, RwLock, 可变性, 内部可变性, 借用冲突Key capabilities
- →Diagnose mutable borrow conflicts
- →Implement interior mutability using Cell/RefCell
- →Select thread-safe synchronization for concurrent access
- →Distinguish between immutable builders and mutation
- →Trace borrow scope violations
How it works
Triggers a decision-tree analysis to determine if shared mutable state requires thread-safe primitives or structural decomposition.
Inputs & outputs
When to use m03-mutability
- →Fixing E0596 cannot borrow as mutable
- →Resolving E0502 borrow conflicts
- →Implementing thread-safe interior mutability
- →Selecting between Cell, RefCell, or Mutex
About this skill
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:
-
Is mutation necessary?
- Maybe transform → return new value
- Maybe builder → construct immutably
-
Who controls mutation?
- External caller →
&mut T - Internal logic → interior mutability
- Concurrent access → synchronized mutability
- External caller →
-
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 |
| Data structure design | m09-domain |
| Anti-patterns | m15-anti-pattern |
When not to use it
- →If the code uses unsafe blocks that bypass borrow checker rules
- →If the problem is a logic error rather than a borrow conflict
Limitations
- →Does not automatically fix deadlocks in multi-threaded code
- →Requires deep understanding of the application's concurrency model
How it compares
Provides a strategic approach to mutability architecture instead of trial-and-error placement of 'mut' or 'RefCell'.
Compared to similar skills
m03-mutability side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| m03-mutability (this skill) | 1 | 6mo | No flags | Advanced |
| debug-cli | 1 | 8mo | Review | Intermediate |
| fix-clippy | 3 | 6mo | No flags | Beginner |
| handling-rust-errors | 4 | 2mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by actionbook
View all by actionbook →You might also like
debug-cli
antinomyhq
Use when users need to debug, modify, or extend the code-forge application's CLI commands, argument parsing, or CLI behavior. This includes adding new commands, fixing CLI bugs, updating command options, or troubleshooting CLI-related issues.
fix-clippy
quickwit-oss
Fix all clippy lint warnings in the project
handling-rust-errors
hashintel
HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.
search-code
JamieMason
Search for code patterns in Syncpack. Use when finding symbols, implementations, or understanding how code is used. Covers ast-grep for Rust and grep/rg for other cases.
m01-ownership
actionbook
CRITICAL: Use for ownership/borrow/lifetime issues. Triggers: E0382, E0597, E0506, E0507, E0515, E0716, E0106, value moved, borrowed value does not live long enough, cannot move out of, use of moved value, ownership, borrow, lifetime, 'a, 'static, move, clone, Copy, 所有权, 借用, 生命周期
bisect-ssa-pass
noir-lang
Workflow for debugging SSA pass semantic preservation using the noir-ssa CLI. Use when a program's behavior changes incorrectly during the SSA pipeline - bisects passes to identify which one breaks semantics. The `pass_vs_prev` fuzzer finds such issues automatically.