diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index a3bf01b..6876015 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -327,7 +327,8 @@ Index: `.claude/memory/MEMORY.md` - **Coding standards:** `.claude/CODING_GUIDELINES.md` - **Ollama connection + examples:** `.claude/OLLAMA.md` - **PROJECT_STATE locking protocol:** `.claude/PROJECT_STATE_PROTOCOL.md` +- **Temp directory graduation workflow:** `.claude/TEMP_GRADUATION.md` --- -**Last Updated:** 2026-04-20 +**Last Updated:** 2026-05-29 diff --git a/.claude/TEMP_GRADUATION.md b/.claude/TEMP_GRADUATION.md new file mode 100644 index 0000000..dba1769 --- /dev/null +++ b/.claude/TEMP_GRADUATION.md @@ -0,0 +1,172 @@ +# 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 + +```bash +# 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//scripts/` | DELETE | +| **Is it general MSP automation?** | GRADUATE to `.claude/scripts/` | DELETE | +| **Is it project tooling?** | GRADUATE to `projects//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//scripts/` | Bardach contact dedup suite, VWP BEC investigation | +| Project tools | `projects//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**: + ```python + """ + Purpose: One-line description of what this does + Usage: python script.py + Author: + 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**: + ```bash + 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 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: + +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/" 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