defrag

---
name: defrag
description: >
  Weekly vault defragmentation. Runs a 5-phase structural audit: inbox hygiene,
  area completeness, project archival, MOC refresh, tag consistency, structure
  evolution, and generates a report. Triggers:
  EN: "defragment the vault", "reorganize the vault", "structural maintenance", "vault defrag", "weekly defrag".
  IT: "deframmenta il vault", "riorganizza il vault", "manutenzione strutturale", "defrag settimanale".
  FR: "defragmenter le vault", "reorganiser le vault".
  ES: "desfragmentar el vault", "reorganizar el vault".
  DE: "Vault defragmentieren", "Vault reorganisieren".
  PT: "desfragmentar o vault", "reorganizar o vault".
---

## Vault Path Resolution

Read `Meta/vault-map.md` (always this literal path) to resolve folder paths. Parse the YAML frontmatter: each key is a role, each value is the actual folder path. Substitute **only** the vault-role tokens listed in the table below — do NOT substitute other `{{...}}` patterns (like `{{date}}`, `{{Name}}`, `{{YYYY}}`, `{{ISO timestamp}}`, `{{today}}`, `{{Area Name}}`, etc.), which are template placeholders.

If vault-map.md is absent: warn the user once — "No vault-map.md found, using default paths" — then use these defaults:

| Token | Default |
|-------|---------|
| `{{inbox}}` | `00-Inbox` |
| `{{projects}}` | `01-Projects` |
| `{{areas}}` | `02-Areas` |
| `{{resources}}` | `03-Resources` |
| `{{archive}}` | `04-Archive` |
| `{{templates}}` | `Templates` |
| `{{moc}}` | `MOC` |
| `{{meta}}` | `Meta` |

If vault-map.md is present but a role is missing: warn the user — "vault-map.md does not define [role]. What folder should I use?" — and wait for their answer before proceeding.

---

# Weekly Vault Defragmentation

You are executing the Architect's weekly vault defragmentation workflow. This is a structural operation — not a quality audit (that is the Librarian's job). You scan the vault's organizational skeleton, fix structural gaps, evolve the layout, and produce a comprehensive report.

## Golden Rule: Language

**Always respond to the user in their language.** Match the language the user writes in. This skill file is written in English for universality, but your output adapts to the user.

---

## Post-it Protocol

### At the START of execution

Read `{{meta}}/states/architect.md` (if it exists). If it contains an active defrag flow, **resume from the recorded phase** — do NOT restart from Phase 1.

### At the END of execution

Write (or overwrite) `{{meta}}/states/architect.md` with:

```markdown
---
agent: architect
last-run: "{{ISO timestamp}}"
---

## Post-it

### Last operation: defrag
### Summary: {{brief summary of what was done}}
### Issues detected: {{any issues that need follow-up, with suggested agents}}
```

**Max 30 lines** in the Post-it body. If you need more, summarize.

---

## The 5-Phase Defragmentation Workflow

When the user triggers a defrag, execute all 5 phases in order.

### Phase 1: Structural Audit

1. **Scan all files in `{{inbox}}/`** — anything older than 48 hours that is still in Inbox is a failure. Signal the Sorter via `### Suggested next agent` to triage it, or file it yourself if the destination is obvious.

2. **Scan `{{areas}}/`** — for each area:
   - Does it have an `_index.md`? If not, create it.
   - Does it have a corresponding MOC in `{{moc}}/`? If not, create it.
   - Are the sub-folders still relevant? Are there new clusters of notes that warrant a new sub-folder?
   - Are there notes that clearly belong to a different area? Move them.

3. **Scan `{{projects}}/`** — are there completed projects that should be archived to `{{archive}}/`?

4. **Scan `{{resources}}/`** — are there resources that now belong to a specific area? Move them.

5. **Scan `{{moc}}/`** — is the Master Index up to date? Are all area MOCs linked? Are there MOCs with no corresponding area (orphan MOCs)?

6. **Scan `{{templates}}/`** — are there templates that are never used? Are there note types that lack a template?

### Phase 2: Tag Hygiene

1. Scan all notes for tags not listed in `{{meta}}/tag-taxonomy.md` — either add them to the taxonomy or fix them.
2. Look for tag synonyms (e.g., `#ml` and `#machine-learning`) — consolidate.
3. Ensure hierarchical tags are consistent (all area tags use `#area/` prefix).

### Phase 3: MOC Refresh

1. For each MOC, verify that it actually links to the notes it should.
2. Add links to new notes that were created since the last defrag.
3. Remove links to notes that were archived or deleted.
4. Verify that the Master Index (`{{moc}}/Index.md`) links to every area MOC.

### Phase 4: Structure Evolution

1. Check `{{meta}}/user-profile.md` — has the user's situation changed? New jobs, new interests, new goals mentioned in recent notes?
2. If you notice a cluster of 3+ notes on a topic that has no dedicated area or sub-folder, **create the structure proactively** using the Area Scaffolding Procedure (see below).
3. Update `{{meta}}/vault-structure.md` with all changes.

### Phase 5: Report

Create a defragmentation report at `{{meta}}/health-reports/YYYY-MM-DD — Defrag Report.md`:

```markdown
---
type: report
date: "{{today}}"
tags: [report, defrag, maintenance]
---

# Vault Defragmentation Report — {{date}}

## Summary
- Files moved: {{count}}
- Structures created: {{list}}
- Tags fixed: {{count}}
- MOCs updated: {{list}}
- Inbox items triaged: {{count}}
- Projects archived: {{list}}

## Structural Changes
{{Detailed list of what was created, moved, renamed, or archived}}

## Recommendations
{{Suggestions for the user — new areas to consider, templates to create, etc.}}

## Next Defrag
{{Anything to watch for next week}}
```

Log the defrag in `{{meta}}/agent-log.md`.

---

## Area Scaffolding Procedure (Summary)

When Phase 4 detects a new area or sub-area is needed, follow these 7 steps:

1. **Create the folder structure** — create the area folder under `{{areas}}/` with appropriate sub-folders.
2. **Create the area index note** — every area folder gets an `_index.md` with purpose, active projects, sub-areas, key resources, and a link to its MOC.
3. **Create the area MOC** — create `{{moc}}/{{Area Name}}.md` with overview, structure, key notes, active projects, and a link back to the Master Index.
4. **Update the Master MOC** — add a link to the new area MOC in `{{moc}}/Index.md`.
5. **Create area-specific templates** — if the area needs specialized templates (e.g., Finance needs Budget Entry), create them in `{{templates}}/`.
6. **Update `{{meta}}/vault-structure.md`** — document the new area, its sub-folders, and its purpose.
7. **Update `{{meta}}/tag-taxonomy.md`** — add area-specific tags (e.g., `#area/finance`, `#budget`).

For the full detailed procedure with templates and examples, see the Architect agent (`agents/architect.md`, Section 4).

---

## Inter-Agent Coordination

After completing the defrag, analyze your findings and suggest follow-up agents when appropriate. Include a `### Suggested next agent` section at the end of your output for each applicable case:

- **Sorter** — when Inbox has items older than 48 hours, or when notes in `{{resources}}/` should be moved to a newly created area.
- **Connector** — when new MOCs were created that need linking, or when orphan notes (no links) were found.
- **Librarian** — when structural inconsistencies were found that need a full quality audit (broken links, duplicates).

### Output format for suggestions

```markdown
### Suggested next agent
- **Agent**: sorter
- **Reason**: {{why this agent should run next}}
- **Context**: {{specific details about what needs attention}}
```

### When to suggest a new agent

If during defrag you detect a recurring need that no existing agent covers, include:

```markdown
### Suggested new agent
- **Need**: {{what capability is missing}}
- **Reason**: {{why no existing agent can handle this}}
- **Suggested role**: {{brief description of what the new agent would do}}
```

---

## Output Format

Always structure your response as follows:

1. **Announce** the defrag is starting (in the user's language)
2. **Execute** each phase, reporting findings as you go
3. **Generate** the report file at `{{meta}}/health-reports/`
4. **Update** your post-it at `{{meta}}/states/architect.md`
5. **Log** the operation in `{{meta}}/agent-log.md`
6. **Summarize** results to the user with key metrics (files moved, structures created, tags fixed, MOCs updated)
7. **Suggest** next agents if applicable