Add "lessons/sprints/cache-clearing-breaks-mcp-tools-mid-session"

lessons%2Fsprints%2Fcache-clearing-breaks-mcp-tools-mid-session.-.md

@@ -0,0 +1,41 @@
+## Context
+
+During plugin development, following CLAUDE.md instructions to clear the plugin cache mid-session caused all MCP tools to fail with TLS certificate errors.
+
+- Command attempted: `rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/`
+- Error: `Could not find a suitable TLS CA certificate bundle, invalid path: .../certifi/cacert.pem`
+
+## Problem
+
+The CLAUDE.md mandatory rule instructed clearing the cache after plugin updates, but this is destructive mid-session because:
+
+1. MCP tools load with **absolute paths** to the venv at session start
+2. Cache contains the venv with TLS certificates (certifi package)
+3. Deleting the cache removes the venv, but the session still references the old paths
+4. Any HTTP-based MCP tool fails with certificate errors
+
+## Solution
+
+Updated documentation to prevent this scenario:
+
+- **CLAUDE.md**: Replaced "ALWAYS CLEAR CACHE" rule with "VERIFY AND RESTART"
+- **verify-hooks.sh**: Changed cache existence from error to informational message
+- **DEBUGGING-CHECKLIST.md**: Added section "Cache Clearing: When It's Safe vs Destructive"
+
+Key insight: Session restart is required for plugin changes, not cache clearing.
+
+## Prevention
+
+1. **Never clear plugin cache during an active session**
+2. Cache clearing is only safe **before** starting a new session
+3. For plugin changes mid-session: inform user to restart Claude Code
+4. verify-hooks.sh no longer treats cache existence as a failure
+
+## Related
+
+- Issues: #145, #144
+- Branch: `fix/issue-145-cache-clear-instructions`
+- Files modified: CLAUDE.md, scripts/verify-hooks.sh, docs/DEBUGGING-CHECKLIST.md
+
+---
+**Tags:** mcp, cache, session, bug-fix, documentation, venv, tls