Sprint 4 - New Commands Not Discoverable Until Cache Clear

Context

Sprint 4 added the /sprint-diagram command to projman plugin. The command file was properly created with correct YAML frontmatter, added to the installed location, and committed to git.

Problem

After completing Sprint 4, running /sprint-diagram returned:

Unknown skill: projman:sprint-diagram

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 caches plugin files at ~/.claude/plugins/cache/.

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.

~/.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

Clear the plugin cache:

rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/

Restart Claude Code - cache will be rebuilt from installed files
Verify command works:
```
/sprint-diagram
```

Prevention

Add to sprint-close workflow:

If sprint added new commands:
- Document which commands were added
- Clear cache before testing: rm -rf ~/.claude/plugins/cache/<marketplace>/
- Restart session
- Test each new command
- Only THEN mark sprint verified
Update post-update.sh script to include cache clearing option

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

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")