From c5b21035985728f0d8b832300933a01dfcbf28ec Mon Sep 17 00:00:00 2001
From: Leo Miranda <leobmiranda@gmail.com>
Date: Wed, 28 Jan 2026 20:52:03 +0000
Subject: [PATCH] Update
 "lessons%2Fpatterns%2Fsprint-4---new-commands-not-discoverable-until-session-restart.-"

---
 ...ot-discoverable-until-session-restart.-.md | 73 +++++++++++--------
 1 file changed, 42 insertions(+), 31 deletions(-)

diff --git a/lessons%2Fpatterns%2Fsprint-4---new-commands-not-discoverable-until-session-restart.-.md b/lessons%2Fpatterns%2Fsprint-4---new-commands-not-discoverable-until-session-restart.-.md
index 7737803..fc7b8cb 100644
--- a/lessons%2Fpatterns%2Fsprint-4---new-commands-not-discoverable-until-session-restart.-.md
+++ b/lessons%2Fpatterns%2Fsprint-4---new-commands-not-discoverable-until-session-restart.-.md
@@ -1,4 +1,4 @@
-# Sprint 4 - New Commands Not Discoverable Until Session Restart
+# Sprint 4 - New Commands Not Discoverable Until Cache Clear
 
 ## Context
 
@@ -15,57 +15,68 @@ Investigation showed:
 - File exists at `~/.claude/plugins/marketplaces/.../commands/sprint-diagram.md`
 - YAML frontmatter is correct (identical to working commands)
 - Other commands (`/sprint-status`, `/sprint-plan`) work fine
+- **Session restart did NOT fix the issue**
 
 ## Root Cause
 
-**Claude Code discovers skills at session start.** Commands added to the installed location DURING a session are NOT discoverable until the session is restarted.
+**Claude Code caches plugin files at `~/.claude/plugins/cache/`.**
 
-File timestamps revealed:
-| File | Modified | Status |
-|------|----------|--------|
-| sprint-diagram.md | Jan 28 13:46 (during session) | NOT discoverable |
-| sprint-status.md | Jan 28 11:03 (before session) | Works |
+The cache was created on Jan 27 14:58 - BEFORE sprint-diagram was added. Claude Code uses this cached version instead of the installed files, even after session restart.
 
-The Sprint 4 implementation happened, the command was added, but nobody tested it in a NEW session.
+```
+~/.claude/plugins/cache/leo-claude-mktplace/projman/3.2.0/commands/
+├── sprint-status.md    ✓ (in cache)
+├── sprint-plan.md      ✓ (in cache)
+├── sprint-close.md     ✓ (in cache)
+└── sprint-diagram.md   ✗ (NOT in cache - added after cache created)
+```
+
+**Key insight:** Session restart alone does NOT refresh the cache. The cache persists across sessions.
 
 ## Solution
 
-1. **Immediate fix**: Restart Claude Code session - new skills will be discovered
-2. **No code changes needed** - the command file is correct
+1. **Clear the plugin cache:**
+   ```bash
+   rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
+   ```
+
+2. **Restart Claude Code** - cache will be rebuilt from installed files
+
+3. **Verify command works:**
+   ```
+   /sprint-diagram
+   ```
 
 ## Prevention
 
-**Add verification checkpoint to sprint-close workflow:**
+**Add to sprint-close workflow:**
 
-1. **Before marking sprint complete**, if sprint added new commands:
+1. If sprint added new commands:
    - Document which commands were added
-   - Note: "Verification requires session restart"
-   - Create follow-up task: "Verify new commands after restart"
-
-2. **After session restart** (next session):
+   - **Clear cache before testing:** `rm -rf ~/.claude/plugins/cache/<marketplace>/`
+   - Restart session
    - Test each new command
-   - Only THEN mark sprint truly verified
+   - Only THEN mark sprint verified
 
-3. **Update sprint-close.md** to include:
-   ```markdown
-   ## New Command Verification
-   
-   If this sprint added new commands:
-   1. List new commands in sprint close notes
-   2. Remind user: "New commands require session restart to test"
-   3. Create verification task for next session
+2. **Update post-update.sh script** to include cache clearing option
+
+3. **Add to CLAUDE.md mandatory rules:**
+   ```
+   AFTER PLUGIN UPDATES - CLEAR CACHE AND RESTART
+   rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
+   # Then restart Claude Code
    ```
 
 ## Impact
 
-- Hours spent debugging a non-bug
-- User frustration ("spending hours developing something and find out that was never done properly")
-- Sprint 4 marked complete without proper verification
+- Multiple session restarts didn't fix the issue
+- Hours spent debugging
+- User frustration
+- Initial lesson learned was incorrect (said "session restart" when actual fix is "cache clear")
 
 ## Tags
 
-`verification`, `skill-discovery`, `session-cache`, `workflow-gap`, `sprint-4`
-
+`cache`, `skill-discovery`, `plugin-cache`, `workflow-gap`, `sprint-4`, `projman`, `commands`, `debugging`
 
 ---
-**Tags:** verification, skill-discovery, session-cache, workflow-gap, sprint-4, projman, commands
\ No newline at end of file
+**Tags:** cache, skill-discovery, plugin-cache, workflow-gap, sprint-4, projman, commands, debugging
\ No newline at end of file