claudetools/.claude/TEMP_GRADUATION.md

Temp Directory Graduation Guide

Problem

The temp/ directory is gitignored for rapid iteration, but useful scripts disappear during cleanup. We need a deliberate graduation process before mass deletions.

Philosophy

Scratch → Proven → Permanent

1. Scratch — temp/ is the right place for first drafts, one-off investigations, and exploration
2. Proven — Scripts run multiple times, referenced in session logs, or solving recurring problems deserve promotion
3. Permanent — Graduate to proper locations with documentation before cleanup

Before Cleanup: Review Protocol

MANDATORY before running git rm temp/* or similar mass cleanup:

1. Identify Candidates

# Most recently modified (likely still relevant)
ls -lt temp/*.{py,ps1,sh} 2>/dev/null | head -20

# Largest files (substantial work invested)
ls -lhS temp/*.{py,ps1,sh} 2>/dev/null | head -20

# Referenced in recent session logs
grep -r "temp/" session-logs/ --include="*.md" | tail -50

# Multiple executions (appears in bash history or logs)
grep -h "temp/" ~/.bash_history | sort | uniq -c | sort -rn | head -20

2. Graduation Decision Tree

For each candidate file, ask:

Question	Yes →	No →
Was it run more than once?	Keep reviewing	DELETE
Does it solve a recurring problem?	GRADUATE	Keep reviewing
Is it referenced in session logs?	GRADUATE	Keep reviewing
Does it contain unique investigation logic?	GRADUATE (even if one-time, the pattern may recur)	DELETE
Is it client-specific remediation?	GRADUATE to clients/<client>/scripts/	DELETE
Is it general MSP automation?	GRADUATE to .claude/scripts/	DELETE
Is it project tooling?	GRADUATE to projects/<project>/tools/	DELETE

Graduation Locations

Type	Destination	Examples
ClaudeTools automation	.claude/scripts/	onboarding-diagnostic.ps1, post-bot-alert.sh, ksteen-smartbadge-verify.ps1
Client-specific scripts	clients/<client>/scripts/	Bardach contact dedup suite, VWP BEC investigation
Project tools	projects/<project>/tools/	GuruRMM test harnesses, build utilities
General MSP tools	scripts/ (root, create if needed)	Multi-client remediation patterns, generic M365 tools

Graduation Checklist

Before moving a script from temp/ to permanent location:

• Add header comment:

  """
  Purpose: One-line description of what this does
  Usage: python script.py <args>
  Author: <name>
  Created: YYYY-MM-DD
  Last Updated: YYYY-MM-DD
  """
  

• Vault-ize credentials:

  • Replace hardcoded tokens/passwords with vault lookups
  • Example: TOKEN = "abc123" → TOKEN = subprocess.check_output(["bash", VAULT, "get-field", "path", "field"]).decode().strip()

• Test once more:

  • Confirm it still works after credential changes
  • Run with -h or --help if implemented

• Document:

  • Add to relevant README if location has one
  • Or mention in session log with file path and purpose
  • Or add to .claude/REFERENCE.md if it's a key tool

• Rename if needed:

  • temp/vwp_bec_investigation.py → clients/valley-wide-plastering/scripts/bec-investigation.py
  • Use kebab-case for permanent scripts (more readable than underscores)

• Move and commit:

  git mv temp/useful-script.py .claude/scripts/
  git commit -m "chore: graduate temp/useful-script.py to permanent location"
  

Examples from May 2026 Cleanup

What was deleted but might have been worth keeping:

File	Why Keep?	Where?
temp/bardach_dedup_step*.py	5-step contact dedup workflow, could recur for other clients	clients/bardach/scripts/contact-dedup/
temp/vwp_bec_investigation.py	BEC investigation framework (721 lines), reusable pattern	scripts/m365/bec-investigation.py (generalized)
temp/m365_security_scan.py	Tenant security audit, generic tool	scripts/m365/security-scan.py
temp/lonestar-*-2fa-fix.py	2FA remediation pattern	scripts/m365/2fa-remediation.py (generalized) OR clients/lonestar/scripts/

What was correctly kept (already in permanent locations):

File	Location
onboarding-diagnostic.ps1	.claude/scripts/
post-bot-alert.sh	.claude/scripts/
ksteen-smartbadge-verify.ps1	.claude/scripts/

What was correctly deleted (true scratch):

• temp/_debug_graph*.py — debugging iterations, no lasting value
• temp/test-*.ps1 — one-off connectivity tests
• temp/*_output.txt — command output captures
• temp/*_token.txt — ephemeral auth tokens

Integration with Cleanup Commands

If adding a "cleanup temp/" command or script, include this prompt:

[INFO] Found <N> scripts in temp/. Running graduation review...

Recent scripts (modified in last 7 days):
  - temp/foo.py (245 lines, modified 2 days ago)
  - temp/bar.sh (89 lines, modified 5 days ago)

Referenced in session logs:
  - temp/foo.py (3 references in session-logs/2026-05-*.md)

Candidates for graduation: <N>

Options:
1. Review candidates and graduate useful scripts
2. Delete all temp/ scripts (PERMANENT - cannot undo)
3. Cancel

Choice?

Anti-Patterns

DON'T:

• Mass-delete temp/ without review ("clean slate" mindset loses knowledge)
• Graduate everything (temp/ becomes permanent clutter)
• Leave credentials hardcoded in graduated scripts
• Graduate without testing (broken scripts in permanent locations confuse future sessions)

DO:

• Review before cleanup (10 minutes of review saves hours of reconstruction)
• Graduate proven patterns (even if one-time, the investigation logic may recur)
• Generalize when graduating (remove client-specific details from general tools)
• Document purpose (a 2-line comment saves 30 minutes of reverse engineering)

When in Doubt

If uncertain whether a script deserves graduation:

1. Check session logs: grep -r "temp/<filename>" session-logs/
2. Ask: "Would I want this script if a similar problem happens next month?"
3. Bias toward keeping investigation scripts: Even one-time investigations contain patterns worth preserving

Better to graduate 3 scripts that turn out to be useless than to delete 1 script that would have saved hours later.

---

Last Updated: 2026-05-29