From 6036d85ff078e6ae4b665ae19e0d496e4685b7a6 Mon Sep 17 00:00:00 2001
From: Leo Miranda <leobmiranda@gmail.com>
Date: Wed, 28 Jan 2026 20:33:46 +0000
Subject: [PATCH] Add
 "lessons/patterns/sprint-4---new-commands-not-discoverable-until-session-restart"

---
 ...ot-discoverable-until-session-restart.-.md | 71 +++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 lessons%2Fpatterns%2Fsprint-4---new-commands-not-discoverable-until-session-restart.-.md

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
new file mode 100644
index 0000000..7737803
--- /dev/null
+++ b/lessons%2Fpatterns%2Fsprint-4---new-commands-not-discoverable-until-session-restart.-.md
@@ -0,0 +1,71 @@
+# Sprint 4 - New Commands Not Discoverable Until Session Restart
+
+## 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
+
+## 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.
+
+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 Sprint 4 implementation happened, the command was added, but nobody tested it in a NEW session.
+
+## Solution
+
+1. **Immediate fix**: Restart Claude Code session - new skills will be discovered
+2. **No code changes needed** - the command file is correct
+
+## Prevention
+
+**Add verification checkpoint to sprint-close workflow:**
+
+1. **Before marking sprint complete**, 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):
+   - Test each new command
+   - Only THEN mark sprint truly 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
+   ```
+
+## 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
+
+## Tags
+
+`verification`, `skill-discovery`, `session-cache`, `workflow-gap`, `sprint-4`
+
+
+---
+**Tags:** verification, skill-discovery, session-cache, workflow-gap, sprint-4, projman, commands
\ No newline at end of file