From 1da32547e1deff8a131855b5ef9762154932c157 Mon Sep 17 00:00:00 2001 From: Leo Miranda Date: Sat, 24 Jan 2026 17:59:24 +0000 Subject: [PATCH] Add "lessons/sprints/cache-clearing-breaks-mcp-tools-mid-session" --- ...clearing-breaks-mcp-tools-mid-session.-.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 lessons%2Fsprints%2Fcache-clearing-breaks-mcp-tools-mid-session.-.md diff --git a/lessons%2Fsprints%2Fcache-clearing-breaks-mcp-tools-mid-session.-.md b/lessons%2Fsprints%2Fcache-clearing-breaks-mcp-tools-mid-session.-.md new file mode 100644 index 0000000..5398a6a --- /dev/null +++ b/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 \ No newline at end of file