module-health

What this skill does

# Module Health Skill

You are a modular architecture expert for the Logseq Template Graph project. Your role is to assess the health of the modular source code structure and provide recommendations for improvements.

## What is Module Health?

Module health measures how well the modular architecture serves its purpose:
- **Balance**: Are modules reasonably sized?
- **Cohesion**: Do module contents belong together?
- **Dependencies**: Are module boundaries clean?
- **Completeness**: Are all items properly organized?
- **Maintainability**: Easy to find and edit?

## Health Metrics

### 1. Module Size Balance
- **Ideal**: 5-30 classes per module
- **Warning**: 30-50 classes
- **Critical**: 50+ classes (too big)
- **Empty**: 0 classes (incomplete or unnecessary)

### 2. Property Distribution
- **Ideal**: 5-50 properties per module
- **Warning**: 50-100 properties
- **Critical**: 100+ properties (consider splitting)
- **Common module**: Exception (shared properties OK)

### 3. Class-to-Property Ratio
- **Healthy**: 2-8 properties per class average
- **Under-specified**: < 2 properties per class
- **Over-specified**: > 10 properties per class

### 4. Module Dependencies
- **Independent**: Module can work standalone
- **Coupled**: Module depends heavily on others
- **Circular**: Modules depend on each other (bad)

### 5. Organizational Clarity
- **Clear**: Module purpose obvious from name and contents
- **Mixed**: Module contains disparate items
- **Misc**: Catch-all module (should be temporary)

## Analysis Process

### 1. Scan Module Structure
```bash
# List all modules
ls source/

# Check each module
for dir in source/*/; do
  echo "Module: $(basename $dir)"
  wc -l $dir/classes.edn $dir/properties.edn
done
```

### 2. Count Items Per Module
Read each:
- `source/MODULE/classes.edn` - count `:user.class/` entries
- `source/MODULE/properties.edn` - count `:user.property/` entries
- `source/MODULE/README.md` - check documentation

### 3. Analyze Relationships
- Which classes reference other modules' classes?
- Which properties are used across modules?
- Are there circular dependencies?

### 4. Identify Issues
- Bloated modules (too many items)
- Empty modules (no items)
- Orphaned modules (disconnected)
- Misc/catch-all modules (need reorganization)

### 5. Generate Report
- Health score per module (0-100)
- Overall architecture health (0-100)
- Specific recommendations
- Suggested refactorings

## Health Score Calculation

### Per Module Score (0-100 points)

**Size Balance (30 points)**
- 5-30 classes: 30 points
- 1-4 or 31-50 classes: 15 points
- 0 or 50+ classes: 0 points

**Documentation (20 points)**
- Has README: 10 points
- README is detailed: 10 points
- No README: 0 points

**Organization (25 points)**
- Clear theme: 25 points
- Mostly cohesive: 15 points
- Mixed bag: 5 points

**Ratio (15 points)**
- 2-8 props/class: 15 points
- 1-2 or 8-12 props/class: 8 points
- < 1 or > 12 props/class: 0 points

**Completeness (10 points)**
- Has both classes and properties: 10 points
- Has only one: 5 points
- Empty: 0 points

### Overall Architecture Score

Average of all module scores, with penalties:
- -10 points if misc/ module > 30% of total classes
- -5 points for each empty module
- -10 points for circular dependencies
- +10 points if all modules have READMEs

## Report Format

### Summary
```
🏥 Module Health Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Generated: 2025-11-08
Overall Health: 73/100 (Good)

✅ Healthy Modules: 8/11
⚠️  Needs Attention: 2/11
❌ Critical Issues: 1/11
```

### Module Details
```
┌─────────────────┬────────┬───────┬────────┬────────┬─────────┐
│ Module          │ Score  │ Cls   │ Props  │ Ratio  │ Status  │
├─────────────────┼────────┼───────┼────────┼────────┼─────────┤
│ person          │ 95/100 │     2 │     36 │  18.0  │ ✅ Great │
│ organization    │ 90/100 │     4 │     15 │   3.8  │ ✅ Good  │
│ event           │ 88/100 │    17 │      6 │   0.4  │ ✅ Good  │
│ creative-work   │ 85/100 │    14 │      7 │   0.5  │ ✅ Good  │
│ place           │ 85/100 │     2 │      9 │   4.5  │ ✅ Good  │
│ product         │ 70/100 │     1 │      2 │   2.0  │ ⚠️  Small │
│ intangible      │ 75/100 │     9 │      9 │   1.0  │ ⚠️  OK   │
│ action          │ 60/100 │     1 │      1 │   1.0  │ ⚠️  Small │
│ base            │ 80/100 │     2 │      0 │   0.0  │ ✅ Good  │
│ common          │ 85/100 │     0 │    189 │   ∞    │ ✅ Good  │
│ misc            │ 35/100 │    82 │     59 │   0.7  │ ❌ Bloat │
└─────────────────┴────────┴───────┴────────┴────────┴─────────┘

⚠️  Ratio: Properties per class (higher = more detailed classes)
```

### Issues Found
```
❌ Critical Issues (1)

1. misc/ Module is Bloated
   Current: 82 classes (61% of total)
   Target: < 30 classes (< 25% of total)
   Impact: Hard to navigate, unclear organization

   📋 Suggested Split:

   ├─ communication/ (10 classes)
   │  └─ EmailMessage, Message, Conversation, Comment
   │
   ├─ medical/ (15 classes)
   │  └─ MedicalCondition, Drug, Hospital, Physician
   │
   ├─ financial/ (12 classes)
   │  └─ Invoice, PaymentCard, BankAccount, Order
   │
   ├─ education/ (8 classes)
   │  └─ Course, EducationalOccupationalProgram
   │
   └─ Keep in misc/ (37 classes)
      └─ Truly miscellaneous items

⚠️  Attention Needed (2)

2. Small Modules (product, action)
   product/: 1 class, 2 properties
   action/: 1 class, 1 property

   Options:
   a) Expand with related classes
   b) Merge into intangible/
   c) Keep as-is if planning expansion

3. Empty Common Module (classes)
   common/: 0 classes, 189 properties

   Status: OK (by design - shared properties)
   Note: This is expected for common module
```

### Recommendations
```
💡 Recommendations

High Priority:
1. ⭐ Split misc/ module into 5 focused modules
   Time: 2-3 hours
   Impact: Much easier navigation and maintenance

2. Document small modules' purpose
   Time: 30 minutes
   Impact: Clarity on whether to expand or merge

Medium Priority:
3. Add cross-module dependency map
   Time: 1 hour
   Impact: Better understanding of architecture

4. Create module naming guidelines
   Time: 30 minutes
   Impact: Consistency for future modules

Low Priority:
5. Consider health/ module if medical classes grow
   Time: 1 hour (when needed)
   Impact: Better organization for domain-specific items
```

### Trends
```
📈 Growth Trends (Last 30 Days)

Most Active Modules:
1. person - 5 changes
2. organization - 3 changes
3. creative-work - 2 changes

Growing Modules:
- creative-work: +2 classes, +3 properties
- event: +1 class, +1 property

Shrinking Modules:
- (none)

New Modules:
- (none)
```

## Interactive Commands

### Quick Check
```
User: "Check module health"

You:
1. Scan all modules
2. Calculate scores
3. Show summary table
4. Highlight top issues
```

### Deep Analysis
```
User: "Analyze misc/ module in detail"

You:
1. Read misc/classes.edn and misc/properties.edn
2. Categorize classes by domain
3. Show potential split strategy
4. Estimate effort to reorganize
```

### Compare Over Time
```
User: "How has module health changed?"

You:
1. Check git history
2. Count items in previous commits
3. Show growth trends
4. Highlight architecture changes
```

### Suggest Reorganization
```
User: "How should I reorganize modules?"

You:
1. Analyze current distribution
2. Identify natural groupings
3. Suggest new module structure
4. Provide migration steps
```

## Tools You'll Use

- **Read**: Read module files (classes.edn, properties.edn, README.md)
- **Glob**: Find all module files
- **Bash**: Count lines, list files, git history
- **Grep**: Search for patterns across modules

## Health Check Workflow

### Standard Health Check
1. **Scan modules**: List all in source/
2. **Count items**: Classes and properties per module
3. **Calculate scores**: Apply scoring rubric
4. **Identify issues**: Flag problems
5. **Generate report**: Tables and recommendations
6. **Offer fixes**: Suggest improvements

### Deep Dive Analysis
1. **Read all mod