---
name: workspace-hygiene
description: "Keep the session workspace clean: separate process files (safe to delete at any time) from delivery files (what the user takes away), put every delivery in an outputs/YYYYMMDD-topic-keyword/ folder (except WeChat Official Account / Xiaohongshu / Douyin assets, which go in the platform folders), name files to one convention, and maintain INDEX.md and 00-delivery-notes.md. Use when 'the files are a mess', 'tidy the folder', 'where do deliverables go', 'naming convention', 'clean up at the end', 'outputs is full of loose files', 'package it up and send it to the user'; not responsible for in-project version pile-up, cost accounting or licence accounting (that is asset-management)."
---

> Original skill · commissioned by the user · English edition, 2026-11-12

# Workspace Hygiene

## 0. One-sentence principle

**Whether a file should stay is decided by "who opens it and when", not by how hard it was to make.**

Files for your own reproduction go in `work/`; files the user takes away go in `outputs/<date>-<topic>/`; the two must never mix.

**Scope**: any agent that produces files in a session directory — Codex, Claude Code, DSH and the like. Session directories generated by the application (e.g. `new-chat-3`) **must not be renamed** — the path is how the application identifies the session; cleanliness happens **inside** the session (`work/` and `outputs/`) and at the moment files are handed over.

## 1. Three zones

| Zone | Path | Lifecycle | In delivery | Cleanup policy |
|---|---|---|---|---|
| process zone | `work/` | expires when the session ends | no | **can be deleted wholesale**, no need to confirm file by file |
| delivery zone | `outputs/YYYYMMDD-topic/` | held long-term by the user | yes | add only, never restructure; old versions go to `_deprecated/` |
| index | `outputs/INDEX.md` | lives as long as the deliveries | — | updated on every delivery, newest at the top |

The session root may only contain configuration files such as `AGENTS.md`, `HANDOFF.md`, `CLAUDE.md`, `.gitignore`; every other file belongs to one of the two zones above.

### 1.1 Exception: social-platform assets (takes priority over `outputs/`)

When a deliverable is image or video material for a **WeChat Official Account, Xiaohongshu or Douyin**, **skip `outputs/`** and put it in the matching platform folder under the workspace root:

```
wechat/<YYYYMMDD>_<topic>/     xiaohongshu/<YYYYMMDD>_<topic>/     douyin/<YYYYMMDD>_<topic>/
```

- Naming switches to `YYYYMMDD_topic_purpose[_vN].ext` (the separator between date and topic is `_`, not `-`), because these three directory trees are already built that way and carry an INDEX.
- Every batch still needs `00-delivery-notes.md`, registered in `<platform>/INDEX.md`.
- The same batch of files may exist in only one place; it must not appear in both `outputs/` and a platform folder.
- Full terms are in the workspace `delivery-path-rules.md`; on conflict that file wins.

## 2. The four delivery questions (decision gate)

Ask in order; **all four must be "yes" before anything enters outputs**:

1. **Audience**: is this a finished piece for the user or an outside reader, rather than middleware for your own reproduction?
2. **Self-contained**: does it open directly on another computer (no dependence on local fonts, absolute paths, login state, temporary assets)?
3. **Nameable**: can it be stated as "date-topic-type", without words like "final2"?
4. **Pointable**: within 10 seconds of opening the folder, does the user know which file to click?

Any "no" → keep it in `work/`. When in doubt, default to `work/`: a lost process file can be rebuilt, but **junk mixed into a delivery folder permanently pollutes the user's search**.

**Looks like a deliverable but is not**: raw screenshots / screen recordings, debug scripts, logs, caches, intermediate frames, extracted frames, audio previews, draft A/B, test output, `node_modules` / `.venv`, prompt drafts.

## 3. Naming formula (three mandatory segments + three on-demand segments)

**Folder**: `YYYYMMDD-topic[-scope]`
**File**: `YYYYMMDD-topic[-sequence]-type[-qualifier][-vN].ext`

**Three mandatory**: date, topic, type. **Three on demand**: sequence (multiple items), qualifier (multiple channels / specs), version (old and new coexist).

| Segment | Mandatory | Values | Notes |
|---|---|---|---|
| date | yes | 8 digits | the date of first delivery; rework and re-submission do not rename |
| topic | yes | 2–12 characters, **no `-` inside the segment** | the project name as the user says it, not an internal codename |
| sequence | when multiple | `EP01`, `P02`, `03` (two-digit zero padding) | which item of the same topic this is |
| type | yes | finalcut / cover / subs / script / copy / carousel / audio / data / notes | a fixed vocabulary, do not invent synonyms |
| qualifier | when ambiguous | channel → aspect ratio → language → duration | only the minimum segments needed to remove ambiguity |
| version | when old and new coexist | `v2`, `v3` | old versions move to `_deprecated/`; do not reuse v1 |

**Uniqueness ladder**: ask from the top down, stop at the first hit, add only the segment that removes the ambiguity.

1. Several different things on the same day → **different topics**
2. Several items for the same topic → **add a sequence**: `20261018-errorclinic-EP01-finalcut.mp4`
3. The same item delivered to several channels / aspect ratios → **add a qualifier**: `...-finalcut-xiaohongshu.mp4`, `...-finalcut-9x16.mp4`
4. The same spec revised several times → **add `-v2`**, and move the old version into `_deprecated/`

**Two acceptance tests**:

- **Out-of-folder test**: send the file on its own over WeChat — from the filename alone, can you say "which episode, what content, what spec"?
- **Side-by-side test**: put any two files from the same directory side by side — can you tell them apart without opening them?

| Scenario | Not clear enough | Clear |
|---|---|---|
| three short videos in one day | `20261018-finalcut.mp4` ×3 | `20261018-errorclinic-EP01-finalcut.mp4` |
| one video, both landscape and portrait | `...-finalcut-horizontal/vertical` | `...-finalcut-16x9.mp4` / `...-finalcut-9x16.mp4` |
| one video on two platforms | `...-finalcut-final.mp4` | `...-finalcut-xiaohongshu.mp4` / `...-finalcut-channels.mp4` |
| Chinese and English subtitles | `...-subs.srt` ×2 | `...-subs-zh.srt` / `...-subs-en.srt` |
| one draft, several revisions | `...-script-final2.md` | `...-script-v2.md` |
| three episodes delivered at once | three folders | `20261018-errorclinic-EP01-03/`, containing three EP files |

Convention details: segments are separated by `-`, and **`-` is forbidden inside a segment** (use `·` or join the words); no spaces, no full-width brackets, no `final/new/copy`; keep filenames under 90 characters.

## 4. Action sequence for one delivery (3–5 minutes)

0. **Trigger (default behaviour)**: whenever this session produced a file the user might want, run this section at wrap-up without waiting to be asked
1. **Look at the current state**: `tidy_check.py check --root .`
2. **Put things in place**: for every loose file in the root and in the outputs root, decide → delivery folder / `work/`
3. **Run the four questions**: anything that fails moves back to `work/`
4. **Write two pages**: `00-delivery-notes.md` (what it is, which file to send) + `INDEX.md` (one row for this batch, newest at the top)
5. **Re-check**: run `check` again, and **exit code 0 is the only finish line**

```powershell
# Start a new batch (creates the folder, writes delivery notes, registers the index)
python <SKILL_DIR>\scripts\tidy_check.py new --root . --topic file-hygiene --summary "zones and naming convention for the session workspace"

# Session-level check
python <SKILL_DIR>\scripts\tidy_check.py check --root .

# Sweep a whole date directory (treats each first-level subdirectory as a session)
python <SKILL_DIR>\scripts\tidy_check.py check --root "<WORKSPACE>/sessions/<YYYY-MM-DD>"

# Machine-readable result + strict mode (advisories also count as failures)
python <SKILL_DIR>\scripts\tidy_check.py check --root . --json work\tidy.json --strict
```

The script only scans read-only and changes no files; its only write operation is the `new` subcommand (which supports `--dry-run` for a rehearsal). Across time zones, pass `--date YYYYMMDD` explicitly instead of relying on the machine's date.

## 5. Hard gates (five)

1. **No loose files in the outputs root** (only `INDEX.md` is allowed).
2. **Delivery folders must carry an 8-digit date prefix**; filenames must pass the **out-of-folder test** — after leaving the folder they must still reveal topic, sequence and spec. The version number goes in the filename only, never in the folder name.
3. **Every delivery folder must contain `00-delivery-notes.md`**, with a registered row in `INDEX.md` whose link opens.
4. **Nothing in `work/` ever enters a delivery**; delivery folders stay flat, with `_deprecated/` as the only allowed subdirectory.
5. **Move, do not delete**: old versions go to `_deprecated/`; if something really must be deleted, list it for the user's approval first (a past "cleanup" on the workstation destroyed many project directories at once).

## 6. Anti-patterns (measured on the workstation)

| Anti-pattern | Measured consequence |
|---|---|
| letting session directories be called `new-chat` | most sessions in one audit were `new-chat`-like and could not be found by name afterwards |
| delivery files lying flat in the outputs root | in one session every file sat in the outputs root, and finding the main file meant paging through them |
| naming delivery folders at will | only a small fraction of delivery folders carried a date prefix |
| using "final / latest" to express a version | after sorting you still cannot tell which is newest, and old and new cannot coexist |
| writing only "date-type" (e.g. `20261018-cover.png`) | two things on one day collide, and outside the folder it is unrecognisable |
| delivering one identically named file for multiple episodes / platforms | three `finalcut.mp4` side by side in WeChat, with no way to tell which is which |
| treating screenshots, scripts and logs as deliverables | the user has to pick one file out of dozens |

## 7. Division of labour with other skills

| Skill | Handles |
|---|---|
| **this skill** | session level: which files survive, where they go, what they are called, how they are registered — **the single source of truth for placement and naming** |
| `asset-management` | project level: version pile-up checks, cost accounting, licence accounting, cross-project asset reuse |
| `save-to-desktop` | only the "save to desktop" action |

Stacking order: **place and name per this skill first, then build the ledger with asset-management**; when the two conflict, this skill wins for deliverable naming.

## 8. When you need the details

Read `references/naming-and-judgement-rules.md`: naming grammar and the disambiguation decision tree (§8), the safe process for bulk-renaming existing files, series deliveries, cross-day / rework cases, English topics, Git repository scenarios, and boundary-dispute judgement.