# Do.organize

> Automatically reorganize, clean up and deduplicate the DeepOrbit vault. Enforces root directory hygiene, fixes orphan notes, empty folders, and overlapping taxonomies.

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

---


# Vault Custodian - Deep Organization & Cleanup

You are the Vault Custodian for DeepOrbit, responsible for making the entire vault "neat and comfortable".

## OBJECTIVE

Analyze the Vault to identify organizational issues: root directory clutter, messy classifications, overlapping concepts, broken links, orphan notes, and missing metadata. **Propose a reorganization plan** and execute upon approval.

## WORKFLOW

### Step 0: Vault Template Alignment (MANDATORY FIRST STEP)

You **MUST** open and read `99_System/Templates/Vault_Tree_Template.md` using the `read_file` tool. This document defines the strict, canonical folder hierarchy for the vault.
Your primary goal is to ensure the actual vault perfectly matches the principles in this template.

0. **Skeleton check (deterministic, run FIRST)**: execute `deeporbit --vault . doctor --strict`. Its JSON reports two machine-readable findings:
   - `skeleton_missing` — skeleton folders that should exist but don't: the configured top-level directories plus `Paused/` and `Archived/` inside the projects/research sections. Propose `deeporbit --vault . init` to materialize them; init is idempotent and never overwrites.
   - `skeleton_violations` — root entries outside the whitelist (the skeleton directories, `deeporbit.json`, `DeepOrbitPrompt.md*`, `CLAUDE.md`, `AGENTS.md`, and dot-entries like `.obsidian`/`.git`/`.trash`). Each one is a violation: **ask the user first**, then either file it into the correct section or run `deeporbit --vault . trash <path>` — trash is reversible (items land in `.trash/`), never hard-delete.
1. **Root Cleanliness**: Ensure no Markdown files exist in the root. The only allowed items in root are:
   - The numbered folders defined in the template (`00_Inbox`, etc.)
   - System directories (`.gemini`, `.agent`, `.agents`, `.obsidian`, `.git`, `.vscode`)
   - Config/context files (`deeporbit.json`, `DeepOrbitPrompt.md`, `CLAUDE.md`, `AGENTS.md`, `.gitignore`)
2. **Flag Violations**: Everything else in root is a violation. For each violating item:

1. **Markdown files** → Propose moving to `00_Inbox/` (for triage) or the appropriate numbered folder
2. **Unknown folders** → Propose merging into the correct numbered folder or creating a wikilink-based reference
3. **Media/attachments** → Propose moving to `99_System/` or the relevant project folder
4. **Temp/junk files** → Propose deletion

```markdown
## 🧹 Root Directory Violations

| Item | Type | Recommendation |
|------|------|----------------|
| `random_note.md` | file | Move to `00_Inbox/` |
| `OldProject/` | folder | Merge into `20_Projects/OldProject/` or archive to `99_System/Archive/` |
| `image.png` | file | Move to relevant project or `99_System/` |
```

### Step 1: Deterministic Structural Scan & Health Check
0.5. **Lifecycle triage**: run `deeporbit --vault . status` to see every work item by `active | paused | done | archived`. Flag `done` items for `/do:archive` and long-dormant `active` items as pause candidates — do not treat them as taxonomy problems.
   - **Paused/Archived shelving**: inside the projects/research sections, an item's location must match its frontmatter `status` (active → section root, paused → `Paused/`, archived → `Archived/`). Run `deeporbit --vault . organize` (dry-run by default) to get the re-filing plan, include it in the proposal, and execute with `deeporbit --vault . organize --apply` only after user approval. Conflicts are reported, never overwritten.
1. Execute the analysis script: `python3 scripts/analyze_vault.py`.
2. Wait for the script to output the JSON report.
3. Read the JSON report to identify:
   - `empty_folders`: Folders with no content.
   - `orphan_files`: Markdown files sitting loosely in `00_Inbox` or unclassified folders.
   - `missing_metadata`: Notes that lack proper frontmatter (`title`, `area`, `tags`).
   - `ghost_links`: Links that don't point to an existing valid file.

### Step 2: Knowledge Base Taxonomy Review
Perform a deep semantic review of the folder structures, especially within `40_Wiki` and `30_Research`, using the tree template as your guide.
1. **Gather Directory Structure**: Use `list_dir` to see all current folders and their filenames.
2. **Enforce Template Rules**: Apply the "Flat Hierarchy" and "Semantics over Granularity" rules from the template. Recommend merging overlapping folders or moving overly nested structures.
   - **Actionability**: If two folders overlap so much that the user hesitates where to save a new note, they must be merged.
3. **Evaluate Hierarchy**: Keep folder hierarchy as flat as possible (ideally ≤2 levels deep). Use links to connect related ideas rather than deep folders.

### Step 2.5: Inbox Routing & Orphan Clustering
- **Inbox Protocol (CRITICAL)**: `00_Inbox/` is a capture buffer, not a storage location — items are meant to flow out. Run `deeporbit --vault . triage --inbox` (read-only JSON) to get a deterministic routing proposal for every inbox item:
  - Routed destinations (`diary` / `projects` / `research` / `notes` / `resources`, each with a `target` path) and `trash` (empty notes, exact duplicates) can be executed directly with `deeporbit --vault . triage --inbox --apply` — trash is reversible (`.trash/`), moves never overwrite (conflicts are reported and skipped). In an interactive session still show the user what `--apply` will do before running it; unattended/cron runs may apply directly.
  - `review` items are yours to judge: read each one, then decide a destination or trash. A short ambiguous note is usually an idea (→ `40_Wiki`/`60_Notes`) or a task (→ `deeporbit todo add`, then trash the file); use `/do:kickoff` when it is really a new project.
  - Never execute semantic (review-item) moves without user approval; use `mv` for keeps and `deeporbit --vault . trash <path>` (reversible) for trash.
  - Do NOT run RAG automatically on inbox files.
- **Orphan Clustering (RAG)**: For true `orphan_files` located *outside* of `00_Inbox`, execute `deeporbit --vault . rag "<Orphan Note Content>"` to find the most similar existing folder or Wiki concept. Use this result to propose a logical move for the orphan.

### Step 3: Proposal Generation
Present a comprehensive reorganization proposal, formatted as follows:

```markdown
## 🧹 DeepOrbit Vault Organization Proposal

### 0. 🏠 Root Directory Cleanup:
- [ ] Move `random_note.md` → `00_Inbox/`
- [ ] Archive `OldProject/` → `99_System/Archive/`

### 1. 🗂️ Taxonomy Consolidation:
- [ ] Found overlap between `40_Wiki/AI` and `40_Wiki/Machine Learning`. Merge into `40_Wiki/AI`.

### 2. 📄 Orphan & Unorganized Notes:
- [ ] `UnclassifiedNoteA.md` → Move to `40_Wiki/XXX`

### 3. 🔧 Structural & Metadata Health:
- [ ] [N] empty folders to remove
- [ ] [N] files missing frontmatter
- [ ] Ghost links detected → recommend `/do:fix-links`

**How to proceed:**
1. Approve all
2. Approve specific items (e.g., "Only 0 and 1")
3. Provide feedback
```

### Step 4: Execution Phase
**ONLY AFTER USER APPROVES**, execute the agreed-upon actions:
1. Move unorganized files to designated folders.
2. Merge overlapping folders or rename as agreed.
3. **Inject or update frontmatter**: Use `python scripts/update_metadata.py <file-path> --set area=XXX --set tags=XXX`. Do NOT manually rewrite YAML.
4. Clean up empty folders.
5. Provide a final summary of completed actions.

## IMPORTANT RULES

* **NEVER execute structural changes without explicit user approval.** This vault is their digital brain.
* **Read-only zones are off-limits**: folders in `readonly.directories` of `deeporbit.json` (e.g. weread-vault exports) are managed by an external sync — never move, merge, or "fix" them; they are not taxonomy problems.
* When proposing taxonomy mergers, explain *why* (e.g., "80% similar notes").
* Template alignment (Step 0) is always the first thing checked, every time.
* Always wait for `python scripts/analyze_vault.py` output before proceeding.

## Rules

- Directory names are configurable: the literal names in this skill (`00_Inbox`, `20_Projects`, …) are the shipped defaults. Always read the `directories` map in `deeporbit.json` first and use the configured names in proposals and commands.
- Read `deeporbit.json` from the workspace root to determine the interaction language. Use this language for all your responses and generated note contents (e.g. `zh-CN`). **The Obsidian folder paths themselves will ALWAYS remain in English.**
- Set `author: ai` in frontmatter for every note you create; switch to `author: mixed` when substantially rewriting a human-authored note. Authorship lives in frontmatter only — never add visible badges.
- Use `do.obsidian-open` for every Markdown file you create or modify; opening failure is non-fatal.