# Cleanup Scripts

> Session-scoped script cleanup for data science projects. Checks scripts/scratch/ for working files that need consolidation into .qmd scripts, flags numbered non-.qmd files in scripts/, and verifies script-output directory correspondence. Use when finishing a coding session, when scripts/scratch/ has accumulated files, or when the user says "clean up scripts", "consolidate scratch", or "check script conventions". Lightweight and fast — reads files, no expensive computation.

- Skill: `musserlab/cleanup-scripts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add musserlab/cleanup-scripts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/musserlab/cleanup-scripts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MusserLab (https://skillmd.com/u/musserlab)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/musserlab/cleanup-scripts

---


# Script Cleanup (Session Scope)

Check and consolidate working scripts from the current session. This skill focuses
on the **current session's work** — for project-wide script health, use `/audit-project`.

---

## When to Run

- Before `/done` at the end of a coding session
- When `scripts/scratch/` has accumulated working files
- When the user asks to clean up or consolidate scripts
- After a long iterative development session with lots of file creation

---

## Steps

### 1. Check `scripts/scratch/`

List all files in `scripts/scratch/`. For each file:

- **Identify the target script:** Based on the filename and conversation context, determine which numbered `.qmd` script this code belongs to. If no matching script exists, it may need a new numbered `.qmd`.
- **Report to user:** Show each scratch file, its proposed destination, and ask for confirmation before consolidating.
- **Consolidate:** Wrap the code in a proper `.qmd` chunk (using the `quarto-docs` skill template) and add it to the target script. Or create a new numbered `.qmd` if needed.
- **Clean up:** Delete the scratch file after successful consolidation.

If `scripts/scratch/` is empty or doesn't exist, report "No scratch files" and move on.

### 2. Check for Convention Violations

Scan `scripts/` (not subdirectories) for files that violate conventions:

- **Numbered non-`.qmd` files:** Files matching `[0-9]*_*.R`, `[0-9]*_*.py`, `[0-9]*_*.Rmd` in `scripts/`. On local, these should be `.qmd` — unless they carry a `# allow-py: <reason>` override comment in the first 20 lines, in which case `.py` is sanctioned. On the cluster, `.py` is the default and is fine without the override. Helpers belong in `R/`/`python/`; superseded scripts in `scripts/old/`.
- **Skip these:** `scripts/old/`, `scripts/scratch/`, `scripts/exploratory/`, unnumbered files (legacy).

For each violation:
- Ask the user: convert to `.qmd`, move to helper dir (`R/` or `python/`), or archive to `scripts/old/`?
- Execute the chosen action.

### 3. Verify Script-Output Correspondence

For each numbered `.qmd` in `scripts/`:

- Extract the number prefix (e.g., `15` from `15a_threshold.qmd`).
- Check that `outs/{number}_{topic}/` exists (using the lettered script convention — all scripts with the same number share one output dir).
- Flag scripts with no output directory (may indicate the script hasn't been run yet, which is fine for `status: development`).

For each output directory in `outs/`:
- Check that a corresponding numbered script exists in `scripts/`.
- Flag orphaned output directories (output dir exists but no script — may be from a deleted/archived script).

### 4. Report

Summarize:
- Scratch files consolidated (count)
- Convention violations found and fixed (count)
- Script-output mismatches (list)

---

## Important Notes

- **This is session-scoped.** It uses conversation context to understand what files belong where. For project-wide structural audits, use `/audit-project`.
- **Never delete without asking.** Always show what will be moved/deleted and get user confirmation.
- **Respect legacy scripts.** Unnumbered `.Rmd` files in `scripts/` are legacy — do not flag them as violations.
- **The hook should prevent most violations on local.** The `enforce-qmd-scripts.sh` hook blocks creation of numbered non-`.qmd` files unless the file content carries a `# allow-py: <reason>` override comment in its first 20 lines. The hook auto-skips on the cluster (detected by `/nfs/roberts/`), where `.py` is the default. This skill catches anything that slipped through, pre-dates the hook, or used the override.