organize-folder

name	organize-folder
description	Organize a folder of Markdown notes into a clearer domain/project knowledge area. Use this skill whenever the user asks to organize, tidy, restructure, classify, link, split, merge, normalize, or review notes in a vault folder. Prefer this skill over ad-hoc editing for multi-note cleanup; it keeps changes scoped, conservative, and reviewable.

Folder Organization

Use this skill to organize a folder in a vault so it becomes a maintainable domain knowledge base rather than a loose collection of notes.

The vault is the primary interface and data model: Markdown notes, Properties, wikilinks, tags, folders, backlinks, Graph, Bases, and Canvas are the substrate.

Core stance

Work like a careful knowledge librarian:

• Keep each run scoped to one folder, topic, tag group, or explicit file set.
• Prefer reading and classifying before editing.
• Prefer small, reversible Markdown changes over broad rewrites.
• Preserve the user's wording unless clarity or structure materially improves.
• Do not invent facts, owners, dates, or relationships.
• Do not create an external index/proposal engine unless the user explicitly asks.

Safety model

Default to two phases:

1. Assess: inspect the selected notes and explain the organization opportunities.
2. Suggest or apply: suggest concrete changes; only apply direct edits when the user asks or when the action is clearly low-risk.

Ask before high-risk actions:

• moving files
• renaming files
• splitting a note
• merging notes
• archiving notes
• deleting content
• rewriting large sections
• changing the meaning of a statement

Low-risk actions can be applied after briefly stating intent, unless the user requested read-only mode:

• add or normalize obvious frontmatter/Properties
• add missing wikilinks where the target note clearly exists
• fix heading levels inside one note
• add a short summary section derived from the note itself
• add aliases based on the exact title or common title variants present in the note

If uncertain, ask.

Recommended workflow

1. Understand the scope

Determine the folder or file set from the user prompt. If the scope is ambiguous, ask one question.

2. Inspect existing notes

List Markdown files in scope. Read enough of each note to identify:

• main topic
• note type
• domain/project
• whether it is canonical or supporting material
• obvious relationships to other notes
• whether it looks stale, duplicated, too broad, or too granular

Use vault-native clues first:

• file path
• title
• headings
• Properties/frontmatter
• tags
• wikilinks
• backlinks if available through tools

3. Classify note types

Use a small vocabulary. Do not over-model.

Recommended types:

• overview — domain landing page or map of content
• architecture — system architecture, module relations, flows
• component — one service, module, package, subsystem, or integration point
• operation — concrete environment operation, deployment, command workflow
• troubleshooting — FAQ, symptom/cause/fix, incident notes
• reliability — stability goals, SLO, risks, drills, resilience planning
• decision — ADR-style decision, tradeoff, chosen direction
• source — meeting notes, interview notes, imported source material
• reference — glossary, terminology, external pointers
• archive — obsolete or superseded material

4. Prefer domain-first directory shape

Keep top-level folders domain/project-first. Inside a domain, recommend type-based subfolders only when there are enough notes to justify them.

Suggested shape:

<Domain>/
  _overview/
  architecture/
  components/
  operations/
  troubleshooting/
  reliability/
  decisions/
  sources/
  archive/

Do not force every folder to contain every subfolder. Empty structure is noise.

5. Produce a concise organization report

For read-only or first-pass work, produce this report:

## Scope

## Current shape

## Recommended structure

## Per-note classification

| Note | Type | Suggested location | Suggested changes |
|---|---|---|---|

## Safe changes I can apply now

## Changes that need approval

## Open questions

Keep the report practical. Avoid large theoretical explanations.

6. Apply changes surgically when approved

When the user approves changes:

• edit existing notes rather than creating new ones unless creation is necessary
• keep each note's meaning intact
• use wikilinks like [[Note Title]]
• preserve existing naming style unless the user asks to change it
• do not touch files outside scope unless the user approves

Properties guidance

Use Properties only when they make future organization easier. Avoid noisy metadata.

Recommended minimal fields:

type: architecture
project: <Domain>
status: active
tags:
  - <domain>

Do not guess owner, created, updated, deadlines, or source URLs.

Linking guidance

Add links when the relationship is semantically clear:

• architecture page mentions a component page
• troubleshooting entry refers to an operation page
• reliability goal references a stability planning page
• decision note explains why an architecture page is shaped a certain way

Avoid link spam. A few high-signal links beat linking every repeated term.

Splitting and merging guidance

Suggest splitting when a note contains multiple independently useful topics, such as architecture plus operations plus FAQ.

Suggest merging when two notes cover the same concept with no clear distinction.

Do not perform split/merge without approval. When suggesting, name the proposed target notes and explain the boundary in one sentence each.

Final response style

Be concise. Report what was inspected, what you recommend, and what needs approval next. If edits were made, summarize the exact files changed.