absolute-dotfiles/.config/opencode/command/analyze-vault.md

description, agent, subtask

description	agent	subtask
Analyze vault structure and organization	general	true

Analyze Vault Structure

This command performs a comprehensive analysis of your vault's structure, content, and organization. It scans all markdown files, extracts metadata, categorizes content, and identifies opportunities for improvement.

What This Command Does

The vault analyzer performs deep structural analysis:

Content Scanning

• Scans all markdown files in the project folder
• Extracts frontmatter metadata (tags, dates, categories)
• Analyzes headings hierarchy and structure
• Identifies internal and external links
• Extracts inline tags and keywords
• Calculates file statistics (size, word count, etc.)

Organization Analysis

• Categorizes files by type (guides, tutorials, reference, architecture, etc.)
• Analyzes folder structure and depth
• Identifies orphaned files (no incoming/outgoing links)
• Detects naming patterns and conventions
• Builds link graph showing connections between notes
• Calculates organization health metrics

Output Includes

• Summary: Total files, folders, size, and health score
• Folder Statistics: File counts, average depth, naming patterns
• Categories: Files grouped by content type with statistics
• Orphans: Isolated files that could be better connected
• Link Analysis: Most referenced files, broken links
• Recommendations: Suggestions for improving organization

Example Output

=== Vault Structure Analysis ===

Project: my-awesome-project
Total Files: 45 markdown files
Total Size: 2.34 MB
Health Score: 78/100

=== Folder Structure ===

docs/                     (32 files, 1.8 MB)
  guides/                 (12 files)
  tutorials/              (8 files)
  architecture/           (6 files)
    decisions/            (5 files)
  reference/              (6 files)

=== Content Categories ===

Guides (task-oriented):        12 files (26.7%)
Tutorials (learning):           8 files (17.8%)
Architecture (explanation):    11 files (24.4%)
Reference (information):        6 files (13.3%)
Uncategorized:                  8 files (17.8%)

=== Orphaned Files ===

Found 4 orphaned files with no links:
  - docs/old-notes.md (0 incoming, 0 outgoing)
  - drafts/temp.md (0 incoming, 0 outgoing)
  - research/abandoned.md (1 outgoing, 0 incoming)

=== Link Analysis ===

Total Links: 234
  Internal: 198 (84.6%)
  External: 36 (15.4%)

Most Referenced Files:
  1. docs/architecture/overview.md (23 incoming links)
  2. docs/guides/quick-start.md (18 incoming links)
  3. README.md (15 incoming links)

=== Recommendations ===

1. Connect orphaned files or consider archiving
2. Add more cross-references between guides and tutorials
3. Create index files for large folders (guides/, reference/)
4. Consider moving 3 files to more appropriate categories
5. Standardize file naming (found mixed conventions)

Your Task

Execute the analyze_vault_structure tool immediately with options based on user arguments:

// Parse optional arguments
const args = '$ARGUMENTS';
const noCategories = args.includes('--no-categories');
const noOrphans = args.includes('--no-orphans');
const maxFilesMatch = args.match(/--max-files[=\s](\d+)/);
const maxFiles = maxFilesMatch ? parseInt(maxFilesMatch[1]) : undefined;

const result = await analyze_vault_structure({
  include_categories: !noCategories,
  include_orphans: !noOrphans,
  max_file_size_mb: 10,
  max_files: maxFiles,
  exclude_patterns: ['drafts/*', '*.tmp', 'archive/*'],
});

return result;

Usage Examples:

• /analyze-vault - Full analysis with all features
• /analyze-vault --no-categories - Skip content categorization
• /analyze-vault --no-orphans - Skip orphan detection
• /analyze-vault --max-files 500 - Limit to 500 files

Analysis Options

exclude_patterns (optional)

Glob patterns for files/folders to skip:

exclude_patterns: ['drafts/*', '*.tmp', 'archive/*', '.trash/*'];

include_categories (optional, default: true)

Whether to categorize files by content type (guides, tutorials, reference, etc.):

include_categories: true; // Analyze and group by category
include_categories: false; // Skip categorization

include_orphans (optional, default: true)

Whether to identify orphaned files with no links:

include_orphans: true; // Find isolated files
include_orphans: false; // Skip orphan detection

max_file_size_mb (optional, default: 10)

Skip files larger than this size:

max_file_size_mb: 10; // Skip files over 10 MB

max_files (optional)

Limit total number of files analyzed (useful for large vaults):

max_files: 500; // Analyze first 500 files only

Understanding the Results

Health Score (0-100)

Indicates overall vault organization quality:

• 90-100: Excellent organization, consistent structure
• 70-89: Good organization, minor improvements possible
• 50-69: Moderate organization, several areas need attention
• Below 50: Poor organization, significant restructuring recommended

Categories

Files are classified using the Diátaxis framework:

• Guides (task-oriented): How-to documentation
• Tutorials (learning-oriented): Step-by-step learning paths
• Reference (information-oriented): API docs, specifications
• Architecture (understanding-oriented): Design decisions, explanations
• Uncategorized: Files that don't fit clear patterns

Orphaned Files

Files with no connections to the rest of your vault:

• No incoming links: Nothing references this file
• No outgoing links: This file doesn't reference others
• Both: Completely isolated

Consider linking orphans or archiving if obsolete.

Link Analysis

Shows how notes connect:

• High incoming links: Core reference documents
• High outgoing links: Hub or index pages
• Broken links: References to missing files

Common Use Cases

1. Initial Vault Assessment

analyze_vault_structure({
  project_folder: 'my-project',
  include_categories: true,
  include_orphans: true,
});

Understand current state before reorganization.

2. Identify Cleanup Targets

analyze_vault_structure({
  project_folder: 'my-project',
  include_orphans: true,
  exclude_patterns: ['archive/*'],
});

Find files to archive or delete.

3. Verify Organization

analyze_vault_structure({
  project_folder: 'my-project',
  include_categories: true,
});

Check if files are properly categorized.

4. Performance Analysis

analyze_vault_structure({
  project_folder: 'large-project',
  max_files: 1000,
  max_file_size_mb: 5,
});

Analyze large vaults efficiently.

Guidelines for Agents

When running this command:

1. ONLY use the analyze_vault_structure tool - Do NOT perform manual analysis
2. Present results clearly - Show full output with key highlights
3. Explain findings - Help user understand what the analysis means
4. Do NOT:
   • Manually read files or scan directories
   • Parse markdown or extract metadata yourself
   • Build statistics or link graphs manually
   • The tool does everything automatically
5. Your role is to:
   • Call the tool with appropriate parameters
   • Present and explain the results
   • Suggest next steps based on findings

Next Steps After Analysis

Based on the analysis results:

1. If orphans found: Review and either link or archive them
2. If health score low: Consider running /reorganize-notes
3. If categories mixed: Move files to appropriate folders
4. If broken links: Fix or remove invalid references
5. If naming inconsistent: Standardize file names

Related Commands

• /reorganize-notes - Execute reorganization plan based on analysis
• /setup-notes - Configure documentation architecture
• /validate-config - Validate configuration
• /sync-notes - Sync files between local and vault

---

The analyze-vault-structure tool uses intelligent content analysis to provide actionable insights about your vault's organization and health.