mirror of
https://github.com/boxpositron/absolute-dotfiles.git
synced 2026-02-28 03:30:37 +00:00
d928999224
- Add commands: setup-notes, sync-notes, ingest-notes, teleport-notes - Add commands: validate-notes-config, preview-notes-delegation - Add vault organization commands: analyze-vault, reorganize-notes - Update .withcontextconfig.jsonc with delegation patterns - Archive deprecated with-context.ts plugin
295 lines
8.0 KiB
Markdown
295 lines
8.0 KiB
Markdown
---
|
|
description: Analyze vault structure and organization
|
|
agent: general
|
|
subtask: 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:
|
|
|
|
```javascript
|
|
// 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:
|
|
|
|
```javascript
|
|
exclude_patterns: ['drafts/*', '*.tmp', 'archive/*', '.trash/*'];
|
|
```
|
|
|
|
### include_categories (optional, default: true)
|
|
|
|
Whether to categorize files by content type (guides, tutorials, reference, etc.):
|
|
|
|
```javascript
|
|
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:
|
|
|
|
```javascript
|
|
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:
|
|
|
|
```javascript
|
|
max_file_size_mb: 10; // Skip files over 10 MB
|
|
```
|
|
|
|
### max_files (optional)
|
|
|
|
Limit total number of files analyzed (useful for large vaults):
|
|
|
|
```javascript
|
|
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
|
|
|
|
```javascript
|
|
analyze_vault_structure({
|
|
project_folder: 'my-project',
|
|
include_categories: true,
|
|
include_orphans: true,
|
|
});
|
|
```
|
|
|
|
Understand current state before reorganization.
|
|
|
|
### 2. Identify Cleanup Targets
|
|
|
|
```javascript
|
|
analyze_vault_structure({
|
|
project_folder: 'my-project',
|
|
include_orphans: true,
|
|
exclude_patterns: ['archive/*'],
|
|
});
|
|
```
|
|
|
|
Find files to archive or delete.
|
|
|
|
### 3. Verify Organization
|
|
|
|
```javascript
|
|
analyze_vault_structure({
|
|
project_folder: 'my-project',
|
|
include_categories: true,
|
|
});
|
|
```
|
|
|
|
Check if files are properly categorized.
|
|
|
|
### 4. Performance Analysis
|
|
|
|
```javascript
|
|
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._
|