docs: add temp/ graduation workflow guide
- Created .claude/TEMP_GRADUATION.md with review protocol before cleanup - Graduation decision tree and checklist - Examples from May 2026 cleanup (what should have been kept) - Added to CLAUDE.md reference section
This commit is contained in:
@@ -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
|
||||
|
||||
172
.claude/TEMP_GRADUATION.md
Normal file
172
.claude/TEMP_GRADUATION.md
Normal file
@@ -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/<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
|
||||
Reference in New Issue
Block a user