---
name: organize-folder
description: Sort any messy non-code folder - Downloads-style piles, dump/inbox/scratch folders, a project directory full of drafts, exports and references - into a clear structure without losing anything. Surveys first, follows the folder's existing taxonomy, sorts by each file's role (final, superseded draft, external reference, source asset, ambiguous), checksums before calling anything a duplicate, renames on collision, and never deletes without explicit permission. Use for "organize this folder", "sort these files", "clean this up", "file these away". For photos/videos use organize-photos.
---

# organize-folder

Sort a messy folder into a clear structure without losing or destroying anything. The same handful of judgement
calls come up every time a dump folder is sorted - they are encoded here instead of re-derived per session.

## Usage
- "organize <path>" - sort that folder in place.
- "organize <path> into <target>" - file its contents into an existing structure elsewhere.
- No path and no obvious dump folder (`dump`, `inbox`, `scratch`, `_sort`, `misc`, `new`, `Downloads`, the one the
  user just mentioned) -> ask which folder before any batch move.

## Principles
1. **Survey before you sort.** List everything recursively with size and modified time (`Get-ChildItem -Recurse`,
   `find -printf`). A name alone is not enough: same names can differ, different names can be byte-identical.
2. **Find the existing taxonomy first.** Read a few files in sibling/parent folders (`archive/`, `reference/`,
   `final/`, `workspace/` ...) to learn what each bucket really holds, and sort into that. Invent new folders only
   when nothing fits, with self-explaining names (`archive/slide-drafts_2026-06-to-07/`, never `misc2/`).
3. **Sort by role, not file type.** Current deliverable, superseded draft of it, external reference/template,
   source asset consumed into something else (a chart image pasted into a deck), still-useful working doc, or
   genuinely ambiguous. Use dates relative to known milestones, a quick look inside (first lines, PDF text, an image
   glance) and naming patterns.
4. **Checksum before calling anything a duplicate** (MD5/SHA). Equal names or sizes are only a hypothesis.
5. **Never delete - relocate and flag.** Exact duplicates go to `duplicates_safe_to_delete_later/` with a note of what
   each duplicates. The user decides about deleting.
6. **Park ambiguity honestly** in `uncategorized_review/` (or a more specific honest name) and say so.
7. **Rename on collision, never overwrite** (add a date or short descriptor).
8. **Secrets found loose** (`.env`, keys, service-account JSON, password exports): move to `secrets_review/` and
   flag them prominently - the user decides whether to rotate or delete. Never print their contents.
9. **Batch large moves in one script** (> ~15 files): write the whole move plan as one PowerShell/shell script (or a
   CSV plan + small runner) that logs From,To; show/describe it, run it once. It is auditable and reversible.
10. **Verify after moving**: list destinations, confirm the source holds only what you deliberately left, and why.
11. **Leave a dump/inbox folder in place**, empty, unless the user asks for empty folders to be removed
    (`photo-archive/scripts/remove_empty_dirs.py` does it safely: dry run first, `os.rmdir` only removes empty ones).
12. **Close with a short report**: categories and counts, probable duplicates (and of what), what is parked for the
    user's judgement, secrets flagged, confirmation of what is left in the source, where the move log is.

## Workflow
1. Resolve the target folder. 2. Survey (sizes, dates; spot date clusters around milestones).
3. Learn the existing scheme. 4. Classify by role. 5. Checksum duplicate candidates.
6. Write the move plan as one script with a log. 7. Run it. 8. Verify. 9. Report.

## Not for
Restructuring code (that is a refactor: imports, build config, tests). Photos and videos: `organize-photos`.
Remember user-specific preferences (e.g. "folders ending in Docs are archives, not live projects") in the project's
CLAUDE.md, not in this skill.