doc-organizer

Doc Organizer

Skill to organize and categorize existing technical documents into the correct project structure.

Organization Process

Step 1: Inspect current state

Use Glob to find markdown files:

• docs/*.md for loose files at the root of docs
• docs/**/*.md for all files including subfolders

Check existing folders with ls docs/*/.

Step 2: Ask about categories

Present to the user the existing detected categories, plus these suggested ones if they do not exist:

Category	Use
specs/	Specifications of features/systems
planning/	Active implementation plans
archive/	Completed or superseded documents
architecture/	ADRs, architectural decisions
reference/	Technical reference documentation

Ask the user which ones they want to use.

Step 3: Analyze documents and suggest categorization

For each document found:

1. Read content (first ~50 lines)
2. Detect type by keywords:

Detected keywords	Suggested category
"ADR", "Decision", "Status: Accepted/Proposed", "Context", "Consequences"	architecture/
"Specification", "Requirements", "Spec", "Technical Approach"	specs/
"Plan", "Implementation", "Steps", "Timeline", "Goal"	planning/
"Reference", "Guide", "How to", "Examples", "Usage"	reference/

1. Present the analysis to the user: for each file, show detected keywords, suggested category, and ask for confirmation before moving. The user can approve, reject, or choose another category for each file.

Step 4: Execute reorganization

For each confirmed document:

1. Create destination folder if it does not exist: mkdir -p docs/<categoria>/
2. Move file preserving git history: git mv docs/<archivo>.md docs/<categoria>/<archivo>.md
3. Optionally rename to the standard format (ask the user first):
   • Format: YYYY-MM-DD-<name>.md
   • Exception: ADRs use NNNN-<name>.md

Step 5: Final summary

Show the result: how many files per category, list of reorganized files, and files that remained uncategorized (if any).