Folder organization analyzer

Folder Organization Analyzer

Category: Knowledge Management Subcategory: File Organization Status: Active Created: 2024-01-31 Author: Sasha

---

🎯 Overview

The Folder Organization Analyzer is an intelligent skill that examines folder contents, understands what's there contextually, and recommends the best organizational structure and tagging strategy for your specific content.

Unlike prescriptive organizational standards, this skill adapts to your actual files and proposes tailored solutions.

What This Skill Does

1. Scans folder contents - Analyzes file structure, naming patterns, and content themes
2. Detects existing patterns - Identifies what organizational approach (if any) is already in use
3. Scores folder health - Assesses chaos signals and organizational effectiveness
4. Proposes 4 organizational paradigms - Each tailored to the content found
5. Recommends best approach - With scoring, reasoning, and trade-off analysis
6. Generates migration plan - Step-by-step guidance with specific commands
7. Creates analysis document - Permanent reference saved in the folder

When to Use This Skill

Use when:

• A project folder feels disorganized or hard to navigate
• File count exceeds 15-20 files without clear structure
• Multiple team members need consistent organization
• Starting a new project and want the right structure from the start
• Migrating legacy content to better organization

Don't use when:

• Folder has <5 files (overhead not worth it)
• Organization is already working well
• Temporary or experimental folders
• System directories (skills/, specialists/, etc. - already optimal)

---

📚 The Four Organizational Paradigms

Paradigm 1: Phase-Based Hierarchy

"Organize by workflow stage"

project-folder/
├── 1-research/          # Initial investigation and data gathering
├── 2-analysis/          # Processing and synthesis
├── 3-drafts/            # Work-in-progress deliverables
├── 4-final/             # Completed deliverables
├── 5-archive/           # Historical or superseded materials
└── references/          # Source documents and citations

Best for:

• Executive assessments and research projects
• Sequential workflows (research → draft → final)
• Teams that need to distinguish WIP from completed work
• Projects with clear temporal progression

Indicators that suggest this paradigm:

• Files have date prefixes (YYYY-MM-DD)
• Version indicators in filenames (v1, v2, draft, final)
• Workflow stages mentioned in file names
• Sequential dependencies between documents

Tagging approach:

• phase:research, phase:analysis, phase:final
• status:draft, status:review, status:delivered
• Date-based metadata for progression tracking

---

Paradigm 2: Topic/Entity Clustering

"Organize by subject matter"

project-folder/
├── entity-alpha/         # All materials about Entity A
│   ├── analysis.md
│   ├── financials.md
│   └── sources.md
├── entity-beta/          # All materials about Entity B
├── entity-gamma/         # All materials about Entity C
├── comparative-analysis/ # Cross-entity analysis
└── index.md             # Navigation hub

Best for:

• Competitive analysis and multi-company research
• Portfolio or multi-subject due diligence
• When users need "everything about X"
• Each entity has multiple document types

Indicators that suggest this paradigm:

• Multiple company/person names appear repeatedly
• File names prefixed with entity names
• Each entity has multiple document types
• Users ask for "all materials about [entity]"

Tagging approach:

• entity:company-a, entity:person-b
• type:financial, type:interview, type:analysis
• related:entity-alpha for cross-references

---

Paradigm 3: Artifact-Type Separation

"Organize by file format and function"

project-folder/
├── documents/           # Markdown analysis files
├── data/               # JSON, CSV, structured data
├── scripts/            # Python, JavaScript, automation
├── uploads/            # Source documents (PDF, DOCX, etc.)
├── images/             # Screenshots, diagrams, charts
├── exports/            # Generated outputs
└── README.md           # Project overview

Best for:

• Technical projects with mixed file formats
• Data analysis with automation scripts
• Projects where files are accessed by different tools
• Clear separation between source, process, and output

Indicators that suggest this paradigm:

• Mix of file formats (code, data, docs, images)
• Scripts or automation present
• Data processing workflows
• Technical research projects

Tagging approach:

• format:markdown, format:json, format:python
• function:source, function:processed, function:output
• tool:manual, tool:automated

---

Paradigm 4: Flat with Rich Metadata

"Keep it simple, organize with tags"

project-folder/
├── .index.yml                    # Rich metadata file
├── 2024-01-15-analysis-ceo.md   # ISO date + type + description
├── 2024-01-20-interview-transcript.md
├── 2024-02-01-report-final.md
└── citations.md

Best for:

• Small projects (<15-20 files)
• Well-named, self-describing files
• Single-entity or focused research
• When directory overhead isn't worth it

Indicators that suggest this paradigm:

• File count is small and stable
• Files already well-named and descriptive
• Single focus or entity
• No obvious grouping patterns

Tagging approach:

• YAML frontmatter in each file
• Central .index.yml with comprehensive tags
• File naming: YYYY-MM-DD-[type]-[description].md
• Tags: content-type, subject, status, related-files

---

Paradigm 5: Tag-First Organization

"Minimal folders, rich taxonomy"

project-folder/
├── taxonomy.yml                  # Controlled vocabulary and tag hierarchy
├── [files with rich YAML frontmatter]
├── 2024-01-15-analysis-alpha.md
├── 2024-01-20-research-beta.md
├── 2024-02-01-report-gamma.md
└── index-by-tags.md             # Tag-based navigation hub

Example YAML frontmatter (faceted classification):

---
# Core identification
title: "Market Analysis - Healthcare SaaS Sector"
created: 2024-01-15
updated: 2024-01-30

# Facet 1: Content Type Hierarchy
content-type: analysis
content-subtype: market-analysis
document-format: report

# Facet 2: Subject/Entity Taxonomy
subjects:
  primary: healthcare-saas
  secondary: [telemedicine, ehr-systems, patient-portals]
entities: [healthtech-corp, medrec-solutions, careconnect]

# Facet 3: Project/Phase Context
project: market-landscape-2024
phase: analysis
status: final
version: 2.1

# Facet 4: Methodology & Sources
methodology: [secondary-research, data-analysis]
sources: [gartner-report, company-filings, interviews]
confidence: high

# Facet 5: Audience & Access
audience: [executive-team, investors]
access-level: internal
sensitivity: confidential

# Facet 6: Relationships
related-documents: [2024-01-10-preliminary-research, 2024-02-05-executive-summary]
supersedes: 2024-01-15-analysis-alpha-v1
part-of: market-landscape-2024

# Facet 7: Discoverability
tags: [market-sizing, competitive-landscape, growth-projections]
keywords: [healthcare, SaaS, market-share, TAM, adoption-rates]
---

Best for:

• Cross-cutting content that doesn't fit neat folder boundaries
• Dynamic categorization needs (same doc belongs to multiple categories)
• Search-driven workflows (users search, don't browse)
• Large projects with complex relationships between documents
• Content with multiple independent classification dimensions
• Teams that think in tags, not folders

Indicators that suggest this paradigm:

• Content has multiple equally valid organizational dimensions
• Users ask questions across categories ("All financial analysis for healthcare clients")
• Existing folder attempts keep breaking down (content doesn't fit one bucket)
• Heavy use of search rather than browsing
• Need for faceted filtering (by type AND phase AND entity)
• Cross-references between documents are primary access pattern

Tag taxonomy structure:

• Hierarchical tags: content-type: analysis → content-subtype: market-analysis
• Faceted classification: Multiple independent tag dimensions (type, subject, phase, etc.)
• Controlled vocabulary: taxonomy.yml defines valid tags and their meanings
• Tag relationships: Parent/child, synonyms, related tags
• Tag governance: Who can create tags? How are they maintained?

When tags work better than folders:

1. Multiple categorization needs: Document is simultaneously "analysis" AND "healthcare" AND "Q1-2024"
2. Cross-cutting queries: "All final reports about healthcare from 2024" spans multiple folder dimensions
3. Relationship-driven: Documents link to each other in complex web, not tree
4. Dynamic discovery: Users don't know structure, they search by attributes
5. Collaborative evolution: Tags can be added/refined without restructuring folders

Implementation approaches:

Minimal (Light tagging):

• YAML frontmatter with 3-5 key tags per file
• Simple flat tag vocabulary
• Manual navigation via search

Moderate (Structured tagging):

• YAML frontmatter with faceted classification
• taxonomy.yml with controlled vocabulary
• index-by-tags.md with tag-based navigation

Advanced (Full taxonomy):

• Hierarchical tag structure in taxonomy.yml
• Tag validation and governance
• Automated tag-based index generation
• Search interface or tag browser

Example tag taxonomy (taxonomy.yml):

# Content Type Taxonomy (Hierarchical)
content-types:
  analysis:
    - market-analysis
    - competitive-analysis
    - financial-analysis
  research:
    - primary-research
    - secondary-research
    - literature-review
  reports:
    - executive-summary
    - full-report
    - technical-spec

# Subject Taxonomy (Hierarchical)
subjects:
  industries:
    technology:
      - software
      - hardware
      - saas
    healthcare:
      - telemedicine
      - ehr-systems
      - patient-portals

# Phase Taxonomy (Sequential)
phases:
  - planning
  - research
  - analysis
  - synthesis
  - draft
  - review
  - final

# Status Taxonomy (State machine)
status:
  - draft
  - review
  - approved
  - final
  - delivered
  - archived
  - superseded

# Methodology Taxonomy (Faceted - can have multiple)
methodologies:
  - primary-research
  - secondary-research
  - interview
  - survey
  - data-analysis
  - framework-application

Tag-based navigation example (index-by-tags.md):

# Project Navigation - By Tags

## By Content Type
### Analysis (12 documents)
- [Market Analysis: Healthcare](./2024-01-15-analysis-alpha.md) - healthcare, saas, Q1-2024
- [Competitive Analysis: SaaS](./2024-01-20-analysis-beta.md) - saas, competition, Q1-2024
...

### Reports (8 documents)
- [Executive Summary: Market Landscape](./2024-02-05-exec-summary.md) - final, delivered
...

## By Subject
### Healthcare (15 documents)
- All healthcare-related content regardless of type
...

### SaaS (20 documents)
- All SaaS-related content across healthcare, fintech, etc.
...

## By Phase
### Final (25 documents)
- All completed deliverables across all subjects
...

## By Status × Subject (Matrix)
|             | Healthcare | SaaS | Fintech |
|-------------|-----------|------|---------|
| **Final**   | 8 docs    | 12   | 5       |
| **Draft**   | 3 docs    | 2    | 1       |
| **Review**  | 1 doc     | 0    | 2       |

Tagging best practices:

1. Define taxonomy upfront - Don't let tags grow organically without structure
2. Use controlled vocabulary - Limited set of approved tags
3. Hierarchical where appropriate - industry:healthcare:telemedicine not flat tags
4. Faceted for independence - Content type, subject, phase are independent dimensions
5. Document tag meanings - What does "analysis" mean vs "research"?
6. Governance process - How do new tags get added?
7. Regular cleanup - Remove unused tags, merge synonyms
8. Validate on save - Ensure tags match taxonomy

---

🔍 Analysis Methodology

Step 1: Folder Scan

What the skill examines:

• Total file count and subdirectory count
• File types present (.md, .json, .pdf, .py, etc.)
• Directory depth (how many levels of nesting)
• Files at root vs. in subdirectories
• File naming patterns (dated, versioned, entity-prefixed, descriptive)
• Temporal spread (creation and modification dates)

Step 2: Content Sampling

What the skill reads (lightweight sampling):

• First 1000 characters of each markdown file
• Document titles and headers
• YAML frontmatter if present
• First paragraph to understand purpose
• Presence of tables, lists, code blocks
• Internal links and references

Purpose: Understand semantic themes without deep reading

Step 3: Pattern Detection

The skill detects:

Existing partial organization:

• Are there already subdirectories? What are they named?
• Do file names follow a consistent pattern?
• Is there metadata structure (YAML, .meta files)?

Chaos signals:

• Orphaned files (don't match any pattern)
• Inconsistent naming conventions
• Deep nesting (>4 levels = red flag)
• Duplicate content indicators
• Empty subdirectories

Content themes:

• Entity names mentioned frequently (companies, people)
• Workflow stages mentioned (draft, final, review)
• File format diversity (all docs vs. mixed types)
• Project size (<10, 10-30, 30-50, >50 files)

Step 4: Scoring Each Paradigm

Scoring matrix (0-100 points):

Criterion	Phase-Based	Entity	Artifact	Flat	Tag-First
File count <15	-20	0	0	+30	+10
File count 15-40	+20	+20	+10	0	+20
File count >40	+30	+30	+30	-30	+40
Dated files present	+20	0	0	+10	+10
Multiple entities detected	0	+40	0	0	+30
Mixed file formats	0	0	+40	-10	+10
Existing subdirs by phase	+30	0	0	-10	-20
Existing subdirs by entity	0	+30	0	-10	-20
Existing subdirs by type	0	0	+30	-10	-20
Deep nesting (>3 levels)	-10	-10	-10	+20	+30
Sequential workflow evident	+20	0	0	0	0
Technical project (scripts)	0	0	+30	0	+10
✨ Existing YAML tags present	+10	+10	+10	+20	+40
✨ Cross-cutting content	-10	-10	-10	0	+40
✨ Multiple categorization needs	-20	-10	-10	0	+40
✨ Search-driven access pattern	0	0	0	+10	+30
✨ Complex relationships between docs	0	+10	0	0	+40

New tagging-focused criteria explained:

• Existing YAML tags present - Files already have structured frontmatter with tags
• Cross-cutting content - Documents belong to multiple categories simultaneously
• Multiple categorization needs - Same doc is "analysis" AND "healthcare" AND "Q1"
• Search-driven access - Users search rather than browse folder hierarchies
• Complex relationships - Documents reference each other in web, not tree structure

Recommendation logic:

• Highest score = primary recommendation
• Score differences <15 points = mention both as viable alternatives
• Tag-First often wins when content is cross-cutting or relationship-heavy
• Folders + Tags hybrid common for projects with 30-100 files

Step 5: Generate Analysis Document

Output file: _organization-analysis-YYYY-MM-DD.md

Document sections:

1. Current State Summary - Overview, patterns, chaos signals, themes
2. Primary Recommendation - Paradigm, score, reasoning, proposed structure
3. Alternative Approaches - Other paradigms considered with scores
4. Migration Plan - Step-by-step with actual commands
5. Tagging Strategy - Recommended tags for the chosen paradigm
6. Expected Benefits - What improves after reorganization
7. Maintenance Guidelines - When to reorganize, how to maintain
8. Rollback Plan - How to undo if it doesn't work

---

🚀 How to Use This Skill

🚨 Important: Project Folder Location

When you say "this project" or "organize this project", you mean:

• ✅ Project documentation folder: /home/sasha/all-project-files/deployed-md-files/docs/[project-name]/
• ❌ NOT the working directory: /home/sasha/projects/[project-name]/

Why this matters:

• Working directory (/home/sasha/projects/) contains ONLY configuration files (CLAUDE.md, .claudeignore)
• Documentation directory (/home/sasha/all-project-files/deployed-md-files/docs/) contains ALL research content, files, and project materials
• This skill analyzes and organizes documentation folders, not working directories

Examples:

• User says: "Organize this project" (in setup project)

  • ✅ Analyze: /home/sasha/all-project-files/deployed-md-files/docs/setup/
  • ❌ NOT: /home/sasha/projects/setup/conversation-019/

• User says: "Analyze my company-research folder"

  • ✅ Analyze: /home/sasha/all-project-files/deployed-md-files/docs/company-research/

Invocation

User requests:

• "Analyze the organization of [folder-path]"
• "Help me organize my project folder"
• "Organize this project" (analyzes current project's documentation folder)
• "This folder is getting messy, what should I do?"
• "Recommend an organizational structure for [folder]"

Sasha proactively suggests when:

• Detecting >20 files in flat structure during other work
• User mentions difficulty finding files
• Project growth suggests reorganization needed

Execution Workflow

1. Sasha confirms folder path with user
2. Runs analysis (scan → sample → detect → score)
3. Generates recommendations document
4. Saves to folder as _organization-analysis-YYYY-MM-DD.md
5. Presents summary with primary recommendation
6. Offers migration help if user approves

Example Interaction

User: "My company-research folder is getting messy, can you help organize it?"

Sasha: I'll analyze the folder structure and recommend the best organizational approach.
[Scans /home/sasha/all-project-files/deployed-md-files/docs/company-research/]

Analysis complete! I found:
- 23 files (18 .md, 3 .pdf, 2 .json)
- 3 companies mentioned repeatedly: Acme Corp, TechStart, InnovateCo
- Mix of flat and subdirectory structure
- Some dated files, some entity-prefixed

📊 Primary Recommendation: Entity Clustering (Score: 85/100)

Your folder contains research on 3 distinct companies, each with multiple document types.
Organizing by company will make it easy to find "everything about Acme Corp" in one place.

Proposed structure:
├── acme-corp/
├── techstart/
├── innovateco/
├── comparative-analysis/
└── index.md

I've saved a detailed analysis to:
/home/sasha/all-project-files/deployed-md-files/docs/company-research/_organization-analysis-2024-01-31.md

Would you like me to help with the migration?

---

📖 Example Analysis Output

Here's what the generated analysis document looks like:

Document Header

# Folder Organization Analysis
**Folder:** `/home/sasha/all-project-files/deployed-md-files/docs/company-research/`
**Analysis Date:** 2024-01-31
**Analyzed by:** Sasha - Folder Organization Analyzer Skill

---

## 📊 Current State Summary

**Overview:**
- Total files: 23
- Total subdirectories: 4
- File types: 18 .md, 3 .pdf, 2 .json
- Directory depth: 2 levels
- Date range: 2024-01-10 to 2024-01-31

**Detected Patterns:**
- ✅ Files use consistent date prefix (YYYY-MM-DD)
- ✅ Multiple entities detected: "Acme Corp", "TechStart", "InnovateCo"
- ⚠️ Some files at root, some in subdirectories (mixed approach)
- ❌ No metadata files or YAML frontmatter present

**Chaos Signals:**
- 3 orphaned files that don't match naming pattern
- 2 potential duplicate files (similar names)
- 1 empty subdirectory

**Content Themes:**
- Primary: Competitive analysis of 3 companies
- Secondary: Market landscape research
- Document types: Company profiles, financial analysis, interview transcripts

Primary Recommendation

## 🎯 Recommended Organizational Paradigm

### ⭐ PRIMARY RECOMMENDATION: Entity Clustering
**Score: 85/100**

**Why this fits:**
1. You're analyzing 3 distinct companies with multiple documents each
2. Users will want to find "all materials about Acme Corp"
3. File count (23) is in the sweet spot for entity-based organization
4. Current structure already has some company-specific subdirectories

**Proposed structure:**
[folder-name]/
├── acme-corp/
│   ├── analysis.md
│   ├── financials.md
│   └── interview-transcript.md
├── techstart/
│   ├── analysis.md
│   └── product-overview.md
├── innovateco/
│   ├── analysis.md
│   └── market-position.md
├── comparative-analysis/
│   └── market-landscape.md
├── citations.md
└── index.md (navigation hub)

Alternative Approaches

## 🔄 Alternative Approaches Considered

### Option 2: Phase-Based Hierarchy (Score: 62/100)
**Why considered:** Dated files suggest temporal workflow
**Why not recommended:** Primary access pattern is by company, not by phase
**When to reconsider:** If project shifts to sequential deliverable focus

### Option 3: Flat with Rich Metadata (Score: 45/100)
**Why considered:** Current file count is manageable
**Why not recommended:** 23 files approaching limit for flat structure
**When to reconsider:** If project stays small and entities reduce to 1-2

### Option 4: Artifact-Type Separation (Score: 30/100)
**Why not recommended:** All files primarily documents; no scripts or mixed formats

Migration Plan

## 📋 Step-by-Step Migration Plan

### Phase 1: Preparation (5 minutes)
1. Create backup: `cp -r [folder-name] [folder-name]-backup-[date]`
2. Create new subdirectories:
   ```bash
   mkdir acme-corp techstart innovateco comparative-analysis

3. Create index.md template

Phase 2: File Migration (15 minutes)

Move files to entity folders:

# Acme Corp files
mv 2024-01-15-acme-analysis.md acme-corp/analysis.md
mv 2024-01-20-acme-financials.md acme-corp/financials.md

# TechStart files
mv 2024-01-18-techstart-analysis.md techstart/analysis.md

# [Continue for all files...]

Rename for consistency:

• Remove date prefixes (dates tracked in metadata)
• Use descriptive names: analysis.md, financials.md
• Keep dates in YAML frontmatter

Phase 3: Add Metadata (10 minutes)

Add YAML frontmatter to each file:

---
entity: acme-corp
created: 2024-01-15
updated: 2024-01-31
type: financial-analysis
status: final
tags: [competitive-analysis, financials]
---

Phase 4: Create Index (5 minutes)

[Create navigation hub with links to all entity folders]

Phase 5: Verification (5 minutes)

• Verify all files migrated successfully
• Check for broken internal links
• Confirm metadata is present
• Test navigation via index.md

Estimated total time: 40 minutes

---

## ✅ Expected Outcomes

### After Using This Skill

**Immediate benefits:**
- Clear recommendation based on actual content analysis
- Specific migration plan with exact commands
- Understanding of trade-offs between approaches
- Permanent reference document for the project

**Long-term benefits:**
- Faster file discovery and navigation
- Consistent organization across projects
- Easier onboarding for new team members
- Scalable structure as project grows

### Success Metrics

The analysis succeeds when:
1. Recommended paradigm matches actual content patterns
2. Migration plan is specific enough to execute without guessing
3. User can choose between paradigms with clear understanding
4. Analysis document becomes permanent reference

---

## 🔧 Maintenance & Evolution

### When to Re-analyze

**Trigger re-analysis when:**
- File count doubles from original analysis
- Project scope significantly changes
- New types of content added (e.g., adding scripts to doc-only project)
- Current organization becomes difficult to navigate
- Team grows and needs more formal structure

### How to Maintain Chosen Structure

**Phase-Based:**
- Move files between phases as they progress
- Archive completed work regularly
- Maintain clear naming in each phase folder

**Entity Clustering:**
- Add new entities as subdirectories
- Update index.md when adding entities
- Keep entity folder names consistent (kebab-case)

**Artifact-Type:**
- Be strict about file type placement
- Don't let documents drift into data/ or vice versa
- Keep README.md updated with folder purposes

**Flat + Metadata:**
- Maintain file naming convention consistently
- Update .index.yml when adding files
- Watch file count - reorganize if exceeds 20 files

---

## 🚫 When NOT to Use This Skill

**Don't use for:**
- System directories (skills/, specialists/, prompts/) - already optimal
- Temporary or experimental folders
- Very small projects (<5 files)
- Folders that are already well-organized
- Personal scratch spaces or working directories

**Instead:**
- Trust existing structure if it works
- Use simpler file-labeling approaches for tiny projects
- Focus on content creation, not organization overhead

---

## 🔗 Related Skills

- **file-labeling-system** - Categorizes documents by function (Guide, Research, etc.)
- **markdown-document-standards** - File naming and metadata conventions
- **information-architecture** - UX methodology for organizing content by user mental models
- **transcription-file-naming** - Standardizes naming for transcripts

---

## 📚 Reference Materials

Additional documentation in the `references/` subdirectory:
- `scoring-rubric.md` - Detailed scoring matrix with criteria explanations
- `examples/` - Example analysis outputs for different project types

---

## 🆘 Troubleshooting

### "Analysis recommends a paradigm that doesn't feel right"

**Consider:**
- Check alternative approaches section - was your preference scored?
- Review "When to reconsider" notes for other paradigms
- Scoring optimizes for common patterns - your use case might be unique
- Try the recommendation for a subset of files first

### "Migration seems too complex"

**Options:**
- Start with subset of files (e.g., most recent 10)
- Implement gradually over multiple sessions
- Use simpler Flat + Metadata for now, migrate later
- Keep current structure if it's working adequately

### "Folder content changed significantly after analysis"

**Solution:**
- Re-run analysis to get updated recommendation
- Scoring adapts to new content patterns
- Update analysis document to reflect current state

---

## 📝 Version History

- **v1.0 (2024-01-31)** - Initial release
  - Four organizational paradigms
  - Scoring-based recommendations
  - Migration planning
  - Example analyses

---

**Skill maintained by:** Sasha
**Last updated:** 2024-01-31
**Status:** Active and ready for use

---

*This skill transforms folder organization from a guess-and-check process into a data-driven, systematic approach tailored to each project's unique needs.*