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

```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/<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**:
  ```python
  """
  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**:
  ```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 <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