diff --git a/CLAUDE.md b/CLAUDE.md
index b1b03ce6..01b90225 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -37,6 +37,8 @@
 - Read files >500 LOC in chunks using offset/limit; never assume one read captured the whole file
 - Before every edit: re-read the file. After every edit: re-read to confirm the change applied correctly
 - When renaming anything, search separately for: direct calls, type references, string literals, dynamic imports, re-exports, test files — one grep is not enough
+- Tool results over 50K characters are silently truncated — if search returns suspiciously few results, narrow scope and re-run
+- For tasks touching >5 files: use sub-agents with worktree isolation to prevent context decay
 
 ## JUDGMENT PROTOCOL
 
@@ -50,6 +52,14 @@
 - Try the simplest approach first; if architecture is actually flawed, flag it and wait for approval before restructuring
 - When asked to "make a plan," output only the plan — no code until given the go-ahead
 
+## COMPLETION PROTOCOL
+
+- **NEVER claim done with something 80% complete** — finish 100% before reporting
+- When a multi-step change doesn't immediately show gains, commit and keep iterating — don't revert
+- If one approach fails, fix forward: analyze why, adjust, rebuild, re-measure — not `git checkout`
+- After EVERY code change: build, test, verify, commit. This is a single atomic unit
+- Reverting is a last resort after exhausting forward fixes — and requires explicit user approval
+
 ## SELF-EVALUATION
 
 - Before calling anything done: present two views — what a perfectionist would reject vs. what a pragmatist would ship
@@ -57,6 +67,21 @@
 - If a fix doesn't work after two attempts: stop, re-read the relevant section top-down, state where the mental model was wrong, propose something fundamentally different
 - If asked to "step back" or "going in circles": drop everything, rethink from scratch
 
+## SELF-IMPROVEMENT
+
+- After ANY correction from the user: log the pattern to memory so the same mistake is never repeated
+- Convert mistakes into strict rules — don't just note them, enforce them
+- After fixing a bug: explain why it happened and whether anything prevents that category of bug in the future
+
+## FILE SYSTEM AS STATE
+
+The file system is working memory. Use it actively:
+
+- Write intermediate results and analysis to files in `.claude/`
+- Use `.claude/` for plans, status tracking, and cross-session context
+- When debugging, save logs and outputs to files for reproducible verification
+- Don't hold large analysis in context — write it down, reference it later
+
 ## HOUSEKEEPING
 
 - Before risky changes: offer to checkpoint — "want me to commit before this?"