majiayu000 /quality-report
Generate comprehensive content quality metrics and scores for vault notes using parallel Sonnet sub-agents.
Usage
/quality-report
/quality-report --type Adr # Analyze only ADRs
/quality-report --threshold 60 # Show notes scoring below 60
/quality-report --output markdown # Export to QUALITY_REPORT.md
Instructions
This skill uses 5 parallel Sonnet sub-agents to analyze different quality dimensions concurrently, then produces an overall quality score for each note and the vault.
Phase 1: Launch Parallel Quality Analyzers
Create 5 Task agents running in parallel with model: "sonnet":
Agent 1: Readability Analysis (Sonnet)
Task: Analyze text readability across all notes
- Use Glob to find all *.md files (exclude +Templates/)
- For each note:
- Read content
- Extract body text (exclude frontmatter, code blocks, tables)
- Calculate readability metrics:
* Flesch Reading Ease (0-100, higher = easier)
* Flesch-Kincaid Grade Level (US grade level)
* Average sentence length
* Average word length
* Complex word ratio (words > 3 syllables)
- Score: (Flesch Reading Ease) / 100 * 100 = 0-100
- Return: Map of filename → readability score + metrics
Formula:
Flesch Reading Ease = 206.835 - 1.015(words/sentences) - 84.6(syllables/words)
Flesch-Kincaid Grade = 0.39(words/sentences) + 11.8(syllables/words) - 15.59
Agent 2: Link Density Analysis (Sonnet)
Task: Analyze wiki-link connectivity and density
- Use Glob to find all *.md files
- Build backlink index (which notes link to each note)
- For each note:
- Count outgoing wiki-links (links to other notes)
- Count backlinks (notes linking to this one)
- Calculate link density = links per 100 words
- Identify orphaned notes (0 backlinks)
- Identify hub notes (top 10% by backlinks)
- Check for broken links
- Score calculation:
* Base: min(outgoing_links / 5, 1) * 40 points # Cap at 5 links
* Backlinks: min(backlinks / 3, 1) * 30 points # Cap at 3 backlinks
* Penalty: -20 if orphaned (0 backlinks)
* Penalty: -10 if has broken links
* Bonus: +10 if hub note (top 10%)
- Return: Map of filename → link density score + metrics
Agent 3: Metadata Completeness Analysis (Sonnet)
Task: Validate frontmatter completeness
- Use Glob to find all *.md files
- For each note:
- Parse frontmatter
- Check required fields based on type:
* Universal: type, title, created
* Task: completed, priority, due (optional)
* Project: status, priority, category (optional)
* ADR: status, relatedTo, supersedes, dependsOn, confidence, freshness
* Meeting: date, attendees (optional), project (optional)
* Person: role, organisation (optional), email (optional)
* Page: description (recommended), tags (recommended)
- Check optional quality fields:
* tags (any type)
* description (any type)
* modified (any type)
- Score calculation:
* Required fields: 1 point each (max based on type)
* Optional fields: 0.5 points each
* Quality indicators (ADRs): confidence, freshness, source = 2 points each
* Normalize to 0-100 scale based on note type
- Return: Map of filename → metadata score + missing fields
Agent 4: Section Completeness Analysis (Sonnet)
Task: Check for expected content sections
- Use Glob to find all *.md files
- For each note type, verify expected sections exist:
**ADR sections** (required):
- # Context or ## Context
- # Decision or ## Decision
- # Rationale or ## Rationale
- # Consequences or ## Consequences
- # Alternatives Considered (recommended)
**Meeting sections** (recommended):
- # Agenda or ## Agenda
- # Attendees or ## Attendees (or in frontmatter)
- # Discussion or ## Discussion or ## Notes
- # Action Items or ## Actions or ## Next Steps
**Project sections** (recommended):
- # Overview or ## Overview or ## Summary
- # Status or ## Progress
- # Timeline or ## Milestones
- # Risks or ## Challenges (optional)
**Task sections** (optional, free-form):
- # Description or ## Details
- Score calculation (per type):
* ADRs: 20 points per required section (5 sections = 100)
* Meetings: 25 points per section (4 sections = 100)
* Projects: 33 points per section (3 sections = ~100)
* Others: 100 points (no structure requirement)
- Return: Map of filename → structure score + missing sections
Agent 5: Freshness & Tag Relevance Analysis (Sonnet)
Task: Analyze content freshness and tag quality
- Use Glob to find all *.md files
- For each note:
- Check last modified date (from frontmatter or file stats)
- Calculate days since modification
- Determine freshness category by type:
* Tasks: <7 days = fresh, 7-30 = recent, >30 = stale
* Projects: <30 days = fresh, 30-90 = recent, >90 = stale
* ADRs: <180 days = fresh, 180-365 = recent, >365 = stale
* Meetings: age doesn't matter (scored by completeness)
* Pages: <90 days = fresh, 90-180 = recent, >180 = stale
- Analyze tags:
* Has tags? (yes = good)
* Tag count: 2-5 = optimal, 1 = okay, 0 = poor, >5 = excessive
* Tag relevance: match type-specific patterns (e.g., Projects should have domain tags)
- Score calculation:
* Freshness: 0-60 points based on days since modification (capped by type thresholds)
* Tags: 0-40 points (has tags +20, optimal count +20, else proportional)
- Return: Map of filename → freshness score + days old + tag analysis
Phase 2: Wait for All Agents
Use TaskOutput with blocking to collect results from all 5 agents.
Phase 3: Calculate Overall Quality Scores
For each note, combine the 5 dimension scores:
// Overall Quality Score (0-100)
overallScore = (
readabilityScore * 0.20 + // 20% weight
linkDensityScore * 0.25 + // 25% weight
metadataScore * 0.20 + // 20% weight
structureScore * 0.20 + // 20% weight
freshnessScore * 0.15 // 15% weight
)
// Grade assignment
if (overallScore >= 90) grade = 'A'
else if (overallScore >= 80) grade = 'B'
else if (overallScore >= 70) grade = 'C'
else if (overallScore >= 60) grade = 'D'
else grade = 'F'
Phase 4: Generate Quality Report
# Vault Quality Report
Generated: {{TIMESTAMP}}
Total Notes Analyzed: {{count}}
## 📊 Overall Vault Quality
**Average Score:** {{avg_score}}/100 ({{grade}})
**Distribution:**
- Grade A (90-100): {{count}} notes ({{%}})
- Grade B (80-89): {{count}} notes ({{%}})
- Grade C (70-79): {{count}} notes ({{%}})
- Grade D (60-69): {{count}} notes ({{%}})
- Grade F (<60): {{count}} notes ({{%}})
---
## 🔍 Quality Dimensions
### 1. Readability ({{avg}}/100)
**Top Performers:**
- [[{{note}}]]: {{score}}/100 (Flesch: {{flesch}}, Grade Level: {{grade}})
- [[{{note}}]]: {{score}}/100
**Needs Improvement:**
- [[{{note}}]]: {{score}}/100 (Too complex: Grade {{grade}} reading level)
- [[{{note}}]]: {{score}}/100 (Poor structure: avg {{words}} words/sentence)
**Metrics:**
- Average Flesch Reading Ease: {{avg}} ({{interpretation}})
- Average Grade Level: {{grade}} ({{interpretation}})
- Notes with readability < 50: {{count}}
---
### 2. Link Density ({{avg}}/100)
**Hub Notes (Most Connected):**
- [[{{note}}]]: {{backlinks}} backlinks, {{outgoing}} outgoing
- [[{{note}}]]: {{backlinks}} backlinks, {{outgoing}} outgoing
**Orphaned Notes (No Backlinks):**
- [[{{note}}]]: 0 backlinks, {{outgoing}} outgoing (isolated)
- [[{{note}}]]: 0 backlinks, 0 outgoing (completely isolated)
**Metrics:**
- Average links per note: {{avg}}
- Orphaned notes: {{count}} ({{%}})
- Hub notes (top 10%): {{count}}
- Broken links detected: {{count}}
---
### 3. Metadata Completeness ({{avg}}/100)
**Complete Metadata:**
- [[{{note}}]]: {{score}}/100 (all fields + quality indicators)
- [[{{note}}]]: {{score}}/100
**Missing Metadata:**
- [[{{note}}]]: {{score}}/100 (missing: {{fields}})
- [[{{note}}]]: {{score}}/100 (missing: {{fields}})
**Metrics:**
- Notes with complete required fields: {{count}} ({{%}})
- Notes with tags: {{count}} ({{%}})
- Notes with descriptions: {{count}} ({{%}})
- ADRs with quality indicators: {{count}}/{{total ADRs}} ({{%}})
---
### 4. Structure Completeness ({{avg}}/100)
**Well-Structured:**
- [[{{note}}]]: {{score}}/100 (all sections present)
- [[{{note}}]]: {{score}}/100
**Missing Sections:**
- [[{{note}}]]: {{score}}/100 (missing: {{sections}})
- [[{{note}}]]: {{score}}/100 (missing: {{sections}})
**By Type:**
- ADRs with complete structure: {{count}}/{{total}} ({{%}})
- Meetings with complete structure: {{count}}/{{total}} ({{%}})
- Projects with complete structure: {{count}}/{{total}} ({{%}})
---
### 5. Freshness & Tags ({{avg}}/100)
**Recently Updated:**
- [[{{note}}]]: Updated {{days}} days ago
- [[{{note}}]]: Updated {{days}} days ago
**Stale Content:**
- [[{{note}}]]: {{score}}/100 (last updated {{days}} days ago)
- [[{{note}}]]: {{score}}/100 (last updated {{days}} days ago)
**Tag Analysis:**
- Notes with optimal tag count (2-5): {{count}} ({{%}})
- Notes with no tags: {{count}} ({{%}})
- Notes with excessive tags (>5): {{count}} ({{%}})
---
## 📉 Low-Quality Notes (Score < 60)
| Note | Score | Grade | Issues |
|------|-------|-------|--------|
| [[{{note}}]] | {{score}} | {{grade}} | {{top 2 issues}} |
| [[{{note}}]] | {{score}} | {{grade}} | {{top 2 issues}} |
---
## 📈 High-Quality Notes (Score >= 90)
| Note | Score | Grade | Strengths |
|------|-------|-------|-----------|
| [[{{note}}]] | {{score}} | A | {{top 2 strengths}} |
| [[{{note}}]] | {{score}} | A | {{top 2 strengths}} |
---
## 🎯 Improvement Recommendations
### Quick Wins (High Impact, Low Effort)
1. **Fix Orphaned Notes** ({{count}} notes)
- Add backlinks to: [[{{note}}]], [[{{note}}]], [[{{note}}]]
- Link from relevant MOCs or Projects
2. **Complete Metadata** ({{count}} notes missing fields)
- Add required fields: {{list top 10 notes}}
- Add quality indicators to ADRs: {{list}}
3. **Update Stale Content** ({{count}} notes >{{threshold}} days old)
- Review and update: [[{{note}}]], [[{{note}}]]
- Archive or delete: [[{{note}}]], [[{{note}}]]
### Medium Effort
4. **Improve Readability** ({{count}} notes with score < 50)
- Simplify: [[{{note}}]] (currently Grade {{grade}} level)
- Break up long sentences in: [[{{note}}]]
5. **Add Missing Sections** ({{count}} notes incomplete)
- Complete ADR structure: [[{{note}}]]
- Add meeting action items: [[{{note}}]]
### Long Term
6. **Build Link Network**
- Target average: 3-5 links per note (current: {{avg}})
- Focus on connecting Projects ↔ ADRs ↔ Tasks
7. **Establish Update Cadence**
- Review Projects monthly
- Update ADRs when decisions change
- Archive completed work promptly
---
## 📋 Quality Metrics Summary
| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| Average Score | {{score}} | 80+ | {{status}} |
| Readability | {{score}} | 70+ | {{status}} |
| Link Density | {{score}} | 75+ | {{status}} |
| Metadata | {{score}} | 90+ | {{status}} |
| Structure | {{score}} | 85+ | {{status}} |
| Freshness | {{score}} | 70+ | {{status}} |
| Orphaned Notes | {{count}} | <5% | {{status}} |
| Broken Links | {{count}} | 0 | {{status}} |
---
## 🔄 Next Steps
1. Run `/broken-links` to fix connectivity issues
2. Update stale notes identified in this report
3. Complete metadata for low-scoring notes
4. Re-run quality report in 1 week to track progress
**Export this report:**
```bash
npm run health:markdown > QUALITY_REPORT.md
Schedule automated quality checks:
# .github/workflows/quality-check.yml
on:
schedule:
- cron: '0 9 * * 1' # Monday 9 AM
## Output Modes
1. **Console (default)** - Colorized terminal output
2. **Markdown** - Save to `QUALITY_REPORT.md`
3. **JSON** - Machine-readable format for dashboards
4. **Dashboard** - Interactive HTML (requires export + viewer)
## Use Cases
**Vault Maintenance:**
- Weekly quality checks
- Pre-publication review
- Migration validation
- Cleanup prioritization
**Content Governance:**
- Ensure ADR quality standards
- Project documentation completeness
- Meeting notes follow template
- Metadata compliance
**Continuous Improvement:**
- Track quality trends over time
- Measure impact of improvements
- Identify systematic issues
- Set quality targets
**Knowledge Management:**
- Find isolated knowledge (orphans)
- Improve discoverability (links)
- Maintain freshness (stale detection)
- Optimize readability
## Performance
- **5 parallel agents** = 5x faster than sequential
- **~500 notes**: 45-90 seconds
- **~2000 notes**: 2-4 minutes
- **~5000 notes**: 5-8 minutes
## Notes
- Readability scoring may not apply well to code-heavy notes or technical specifications
- Freshness scoring is type-aware (ADRs can be old if still valid)
- Structure requirements are recommendations, not strict rules
- Link density considers both quality (backlinks) and quantity (outgoing links)
- Excludes templates and system notes from scoring
- Can be run on subsets with `--type` filter