docs(memory): add session 100 learnings

rjmurillo-bot · claude · rjmurillo-bot · commit 211281b2c178 · 2025-12-29T07:34:39.000-06:00
New memories from autonomous PR workflow session: - skill-triage-001-verify-before-stale-closure: Mandatory git history search before closing issues as stale - skill-triage-002-bot-closure-verification: Verify triage bot PR closures citing "superseded" - skill-git-004-branch-switch-file-verification: Verify file state after branch switches - skill-recovery-001-lost-code-investigation: Complete workflow for investigating "lost" code on unmerged branches - pester-variable-scoping: Use $script: prefix for cross-block variable visibility in Pester tests Updated memory-index with new entries. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/.serena/memories/memory-index.md b/.serena/memories/memory-index.md
@@ -9,6 +9,7 @@
 | gh extension notify combine metrics milestone webhook grep sub-issue | skills-gh-extensions-index |
 | label milestone issue create tag priority | project-labels-milestones |
 | powershell ps1 psm1 module pester test discovery isolation | skills-powershell-index, skills-pester-testing-index, pattern-thin-workflows |
+| pester variable scope script BeforeAll It block visibility | pester-variable-scoping |
 | bash exit code cross-language contract AUTOFIX pre-commit hook | skills-bash-integration-index |
 | security vulnerability TOCTOU secret injection | skills-security-index |
 | planning task file path scope breakdown | skills-planning-index |
@@ -33,6 +34,9 @@
 | analysis gap root-cause trade-off git blame investigation | skills-analysis-index |
 | git hook pre-commit autofix cross-language grep TOCTOU | skills-git-hooks-index |
 | git branch merge conflict checkout cleanup workflow resolution worktree parallel isolation | skills-git-index |
+| git branch switch checkout file state verification lost | skill-git-004-branch-switch-file-verification |
+| triage stale closure verify history bot superseded duplicate | skill-triage-001-verify-before-stale-closure, skill-triage-002-bot-closure-verification |
+| lost code recovery investigation unmerged branch orphaned | skill-recovery-001-lost-code-investigation |
 | protocol blocking gate RFC MUST verification template legacy | skills-protocol-index |
 | retrospective learning session failure skill persistence extract | skills-retrospective-index |
 | regex pattern match escape lookahead anchor quantifier | utilities-regex |
diff --git a/.serena/memories/pester-variable-scoping.md b/.serena/memories/pester-variable-scoping.md
@@ -0,0 +1,60 @@
+# Pester Variable Scoping: Use $script: for Cross-Block Visibility
+
+## Problem
+
+In Session 100, a Pester test file triggered PSScriptAnalyzer warning:
+> "The variable 'scriptPath' is assigned but never used"
+
+The variable was defined in `BeforeAll` but used in `It` blocks.
+
+## Root Cause
+
+Pester runs each `It` block in its own scope. Variables defined in `BeforeAll` without `$script:` prefix are not visible in `It` blocks.
+
+## Correct Pattern
+
+```powershell
+# BeforeAll - use $script: prefix
+BeforeAll {
+    $script:scriptPath = Join-Path $PSScriptRoot ".." "path" "to" "script.ps1"
+    $script:testData = @{ key = "value" }
+}
+
+# It blocks - reference with $script: prefix
+Describe "MyTests" {
+    It "Should find file" {
+        Test-Path $script:scriptPath | Should -Be $true
+    }
+    
+    It "Should have test data" {
+        $script:testData.key | Should -Be "value"
+    }
+}
+```
+
+## Anti-Pattern
+
+```powershell
+# BAD - variable not visible in It blocks
+BeforeAll {
+    $scriptPath = "..."  # No $script: prefix
+}
+
+It "Test" {
+    Test-Path $scriptPath  # PSScriptAnalyzer: variable never used
+}
+```
+
+## Scope Reference
+
+| Block | Scope | Visibility |
+|-------|-------|------------|
+| `BeforeAll` | Script/Describe | Use `$script:` for cross-block |
+| `BeforeEach` | It block | Local to each It |
+| `It` | Own scope | Isolated per test |
+
+## Source
+
+- Session 100 (2025-12-29)
+- File: tests/Detect-CopilotFollowUpPR.Tests.ps1
+- PSScriptAnalyzer rule: PSUseDeclaredVarsMoreThanAssignments
diff --git a/.serena/memories/skill-git-004-branch-switch-file-verification.md b/.serena/memories/skill-git-004-branch-switch-file-verification.md
@@ -0,0 +1,51 @@
+# Skill: Verify File State After Branch Switches
+
+## Problem
+
+In Session 100, when switching from `feat/282-centralize-bot-authors` to `main` and then creating `feat/275-unified-rate-limit`, edits to `GitHubHelpers.psm1` were lost because the file reverted to main's version.
+
+## Root Cause
+
+Branch switches reset working directory to the target branch state. Uncommitted or staged changes on the previous branch are lost if not committed first.
+
+## Verification Pattern
+
+After any `git checkout` or branch switch:
+
+```bash
+# 1. Verify current branch
+git branch --show-current
+
+# 2. Check if expected file exists and has expected content
+git diff HEAD~1 --name-only  # See what changed in last commit
+
+# 3. If working on a file that should have edits, verify:
+head -20 {file_path}  # Quick visual check
+```
+
+## Safe Branch Switch Workflow
+
+```bash
+# Before switching branches
+git status  # Check for uncommitted changes
+git stash   # If needed, stash changes
+
+# Switch branch
+git checkout {new-branch}
+
+# After switching
+git stash pop  # If you stashed
+# OR re-apply edits if they belong on the new branch
+```
+
+## Anti-Pattern
+
+```text
+BAD:  git checkout main && git checkout -b new-branch  # Assumes file state preserved
+GOOD: git status && git checkout main && git checkout -b new-branch && verify file state
+```
+
+## Source
+
+- Session 100 (2025-12-29)
+- Lost ~50 lines of edits to GitHubHelpers.psm1
diff --git a/.serena/memories/skill-recovery-001-lost-code-investigation.md b/.serena/memories/skill-recovery-001-lost-code-investigation.md
@@ -0,0 +1,81 @@
+# Skill: Lost Code Investigation Workflow
+
+## When to Use
+
+When code is reported missing, a function "doesn't exist", or an issue references code that can't be found on main.
+
+## Investigation Checklist
+
+### Step 1: Search All Git History
+
+```bash
+# Search for the term across ALL branches (including unmerged)
+git log --all -S "{function_name}" --oneline --source
+
+# If found, shows which branch contains it
+# Example output:
+# f12f237 refs/remotes/origin/feat/pr-162-phase4 feat: Add detection script
+```
+
+### Step 2: Check Related PRs
+
+```bash
+# Search closed PRs
+gh pr list --state closed --search "{keyword}" --json number,title,state,mergedAt
+
+# Look for mergedAt: null (closed without merge)
+```
+
+### Step 3: Check Orphaned Branches
+
+```bash
+# List all remote branches
+git branch -a | grep -i "{keyword}"
+
+# Check if branch still exists
+git ls-tree -r remotes/origin/{branch} --name-only | grep -i "{file}"
+```
+
+### Step 4: Extract and Recover
+
+```bash
+# View file from unmerged branch
+git show remotes/origin/{branch}:{path/to/file}
+
+# Save to current branch
+git show remotes/origin/{branch}:{path/to/file} > recovered_file.ps1
+```
+
+### Step 5: Investigate Why Not Merged
+
+```bash
+# Get PR details
+gh pr view {number} --json title,state,closedAt,body,comments
+
+# Check last comments for closure reason
+```
+
+## Common Causes of "Lost" Code
+
+| Cause | Detection | Recovery |
+|-------|-----------|----------|
+| PR closed without merge | `mergedAt: null` | Recover from branch |
+| Incorrect triage bot closure | "superseded" in comments | Reopen or new PR |
+| Branch deleted after close | No remote branch | Check local or reflog |
+| Bad merge conflict resolution | `git log --all -S` finds it | Cherry-pick |
+
+## Key Principle
+
+**Never trust "doesn't exist" without searching git history.** Code can exist on:
+- Unmerged branches
+- Closed PRs
+- Orphaned commits
+- Stale remote branches
+
+A quick `git log --all -S` search takes seconds and prevents false stale closures.
+
+## Source
+
+- Session 100 (2025-12-29)
+- Issues #238, #293 recovered from unmerged branches
+- PRs #202, #203 incorrectly closed by triage bot
diff --git a/.serena/memories/skill-triage-001-verify-before-stale-closure.md b/.serena/memories/skill-triage-001-verify-before-stale-closure.md
@@ -0,0 +1,46 @@
+# Skill: Verify Git History Before Closing Issues as Stale
+
+## Problem
+
+In Session 100, issues #238 and #293 were incorrectly closed as "stale" because the referenced functions (`Get-CopilotAnnouncement`, `Detect-CopilotFollowUpPR.ps1`) didn't exist on `main`. However, the code existed on unmerged branches (`feat/pr-162-phase4`, `copilot/add-copilot-context-synthesis`) from PRs #202/#203 that were incorrectly closed by triage bot.
+
+## Root Cause
+
+The triage bot closed PRs #202/#203 claiming content was "superseded" because template documentation existed. But the actual **PowerShell implementation** (268 lines) was never merged.
+
+## Mandatory Checklist Before Closing as Stale
+
+```bash
+# 1. Search ALL git history (including unmerged branches)
+git log --all -S "{function_name}" --oneline
+
+# 2. Check for related PRs (open AND closed)
+gh pr list --state all --search "{function_name}"
+
+# 3. Check for orphaned branches
+git branch -a | grep -i "{keyword}"
+
+# 4. If found on unmerged branch, investigate WHY it wasn't merged
+git show {branch}:{file_path} | head -50
+```
+
+## Anti-Pattern
+
+```text
+BAD:  "Function doesn't exist on main" → Close as stale
+GOOD: "Function doesn't exist on main" → Search git history → Found on unmerged branch → Recover
+```
+
+## Recovery Command
+
+```bash
+# Extract file from unmerged branch
+git show remotes/origin/{branch}:{path/to/file} > recovered_file.ps1
+```
+
+## Source
+
+- Session 100 (2025-12-29)
+- Issues #238, #293 (incorrectly closed, then reopened)
+- PRs #202, #203 (incorrectly closed by triage bot)
+- Recovery PR #493
diff --git a/.serena/memories/skill-triage-002-bot-closure-verification.md b/.serena/memories/skill-triage-002-bot-closure-verification.md
@@ -0,0 +1,55 @@
+# Skill: Verify Triage Bot PR Closures
+
+## Problem
+
+In Session 100, PRs #202 and #203 were closed by the triage bot with rationale:
+> "Superseded Content (already on main): Phase 4.5 Copilot Follow-Up Handling already exists in templates/..."
+
+However, only **template documentation** (inline bash examples) existed on main. The actual **PowerShell implementation** (268 lines with structured JSON output, categorization, tests) was never merged.
+
+## Root Cause
+
+Triage bot matched keywords in the template but didn't verify the actual implementation existed.
+
+## Verification Required
+
+When reviewing bot closures that cite "superseded", "already exists", or "duplicate":
+
+```bash
+# 1. Check what the PR was adding
+gh pr view {number} --json files -q '.files[].path'
+
+# 2. Verify those files exist on main
+for file in $(gh pr view {number} --json files -q '.files[].path'); do
+  if [[ -f "$file" ]]; then
+    echo "EXISTS: $file"
+  else
+    echo "MISSING: $file"
+  fi
+done
+
+# 3. If files don't exist, the bot closure was INCORRECT
+```
+
+## Red Flags for Incorrect Bot Closures
+
+| Bot Rationale | Verification |
+|---------------|--------------|
+| "Superseded" | Check if actual code exists, not just docs |
+| "Already exists" | Verify exact file paths, not just concepts |
+| "Duplicate" | Compare actual implementations, not titles |
+
+## Recovery
+
+If bot closure was incorrect:
+
+1. Reopen the original PR, OR
+2. Cherry-pick/recover from the branch: `git show {branch}:{path}`
+3. Create new PR with recovered implementation
+
+## Source
+
+- Session 100 (2025-12-29)
+- PRs #202, #203 (incorrectly closed)
+- Recovery PR #493
+- 268+ lines of implementation recovered
