When to Use This Skill

/quality-report

Generate comprehensive content quality metrics for a Markdown vault. Uses five parallel agents to analyse readability, link density, metadata completeness, structure, and freshness simultaneously, then produces a scored quality report with actionable improvements.

When to Use This Skill

• Quarterly vault health reviews
• Identifying low-quality notes that need improvement
• Measuring knowledge base quality over time
• Finding notes with missing metadata or broken structure
• Prioritising vault maintenance work

Usage

/quality-report [--scope path/to/folder] [--type Meeting|ADR|Concept|all] [--top-issues 20]

Parameters

Instructions

Phase 1: Inventory

1. Scan the vault — List all Markdown files in scope
2. Parse frontmatter — Extract type, tags, dates, and metadata from each note
3. Build file list — Divide notes into batches for parallel processing
4. Report to user: "Found X notes in scope. Launching quality analysis..."

Phase 2: Parallel Quality Analysis — Agent Team

Launch five agents simultaneously using the Task tool. Each agent analyses all notes in scope across one quality dimension.

Agent 1: Readability Analyst (Sonnet) Task: Score readability of note content

• Extract body text (exclude frontmatter, code blocks, YAML)
• Count total words, sentences, and syllables in the body text
• Calculate Flesch Reading Ease using the formula:

  Flesch Reading Ease = 206.835 - 1.015 × (words / sentences) - 84.6 × (syllables / words)
  

• Calculate Flesch-Kincaid Grade Level:

  Flesch-Kincaid Grade = 0.39 × (words / sentences) + 11.8 × (syllables / words) - 15.59
  

• Calculate additional metrics:
  • Average sentence length (words per sentence)
  • Average word length (characters per word)
  • Complex word ratio (proportion of words with >3 syllables)
• Identify notes with very long paragraphs (>300 words without a break)
• Flag notes with no prose content (just bullet lists or tables)
• Score: Clamp Flesch Reading Ease to 0-100, then use directly as the readability score Return: Map of filename → { readabilityScore, fleschEase, gradeLevel, avgSentenceLength, complexWordRatio, issues[] }

Agent 2: Link Density Analyst (Sonnet) Task: Score interconnectedness of notes

• Count outgoing wiki-links per note ([[...]] references)
• Build backlink index (which notes link to each note)
• Count backlinks per note
• Calculate link density (links per 100 words)
• Identify orphaned notes (0 backlinks)
• Identify hub notes (top 10% by backlink count)
• Check for broken links (links to non-existent notes)
• Score each note using the link density formula:

  Base points:     min(outgoing_links / 5, 1) × 40   (cap at 5 outgoing links)
  Backlink points: min(backlinks / 3, 1) × 30         (cap at 3 backlinks)
  Orphan penalty:  -20 if 0 backlinks
  Broken penalty:  -10 if note contains broken links
  Hub bonus:       +10 if note is a hub (top 10% by backlinks)
  

  Final score = clamp(Base + Backlinks + Penalties + Bonus, 0, 100) Return: Map of filename → { linkScore, outgoing, backlinks, linkDensity, isOrphan, isHub, brokenLinks[] }

Agent 3: Metadata Completeness Analyst (Sonnet) Task: Score frontmatter completeness based on note type

• Parse frontmatter from each note

• Evaluate required and recommended fields per type:

  Type	Required Fields	Recommended Fields
  Universal (all)	type, title, created	tags, summary, modified
  Task	+ status, priority	+ completed, due
  Project	+ status	+ priority, category
  ADR	+ status, relatedTo	+ supersedes, dependsOn, confidence, freshness, source
  Meeting	+ date	+ attendees, project
  Person	+ role	+ organisation, email
  Concept/Pattern	(universal only)	+ description, tags

• Score calculation:

  Required fields:    1 point each (based on type-specific count)
  Recommended fields: 0.5 points each
  Quality indicators (ADRs only): confidence, freshness, source = 2 points each
  Normalise total to 0-100 scale based on maximum possible for the note's type
  

Return: Map of filename → { metadataScore, missingRequired[], missingRecommended[] }

Agent 4: Structure Completeness Analyst (Sonnet) Task: Score document structure against expected sections by type

• Define expected sections per note type:

  ADR sections (required — 20 points each, 5 sections = 100):

  • Context (H1 or H2)
  • Decision (H1 or H2)
  • Rationale (H1 or H2)
  • Consequences (H1 or H2)
  • Alternatives Considered (recommended)

  Meeting sections (recommended — 25 points each, 4 sections = 100):

  • Attendees (heading or frontmatter)
  • Agenda
  • Discussion / Notes
  • Action Items / Actions / Next Steps

  Project sections (recommended — 33 points each, 3 sections = ~100):

  • Overview / Summary
  • Status / Progress
  • Timeline / Milestones

  Concept/Pattern sections (recommended — 25 points each):

  • Definition / Overview
  • Context
  • Examples
  • Related

  Other types: 100 points (no structure requirement)

• Check heading hierarchy (H1, H2, H3 nesting)

• Flag empty sections (heading present but no content beneath) Return: Map of filename → { structureScore, missingSections[], emptySections[] }

Agent 5: Freshness and Tag Analyst (Sonnet) Task: Score content freshness and tag quality

• Calculate days since last modification (from modified frontmatter field, falling back to file modification date)

• Categorise freshness using type-aware thresholds:

  Note Type	Fresh	Recent	Stale
  Task	<7 days	7-30 days	>30 days
  Project	<30 days	30-90 days	>90 days
  ADR	<180 days	180-365 days	>365 days
  Concept / Pattern	<90 days	90-365 days	>365 days
  Meeting	Always scored by completeness, not age
  Daily	Always fresh (by definition)

• Freshness scoring (60 points):

  Fresh:  60 points
  Recent: 30 points
  Stale:  0 points
  

  For types where age is irrelevant (Meeting, Daily): award full 60 points.

• Tag scoring (40 points):

  Has tags:             +20 points
  Optimal count (2-5):  +20 points
  Count of 1:           +10 points
  Count of 0:           +0 points
  Count >5 (excessive): +10 points
  Hierarchical format:  no additional points but flag flat tags as issues
  

• Final score = freshness points + tag points (0-100) Return: Map of filename → { freshnessScore, daysSinceUpdate, freshnessCategory, tagCount, tagIssues[] }

Phase 3: Synthesise Quality Report

Combine all agent results:

1. Calculate overall score per note:

   overallScore = readability × 0.20 + linkDensity × 0.25 + metadata × 0.20 + structure × 0.20 + freshness × 0.15
   

2. Assign grades:

   • A: 90-100 (Excellent)
   • B: 80-89 (Good)
   • C: 70-79 (Acceptable)
   • D: 60-69 (Needs Improvement)
   • F: <60 (Poor)

3. Generate report with vault-wide statistics, distribution, and top issues

Scoring Algorithms

This section documents every formula used by the quality agents. Use these as the authoritative reference when implementing scoring.

Readability Score (Agent 1)

Flesch Reading Ease = 206.835 - 1.015 × (total_words / total_sentences) - 84.6 × (total_syllables / total_words)
Flesch-Kincaid Grade = 0.39 × (total_words / total_sentences) + 11.8 × (total_syllables / total_words) - 15.59

Readability Score = clamp(Flesch Reading Ease, 0, 100)

Interpretation:

Syllable estimation heuristic: Count vowel groups (a, e, i, o, u, y) in each word. Subtract 1 for silent-e endings. Minimum 1 syllable per word.

Link Density Score (Agent 2)

base_points     = min(outgoing_links / 5, 1) × 40
backlink_points = min(backlinks / 3, 1) × 30
orphan_penalty  = -20 if backlinks == 0
broken_penalty  = -10 if broken_link_count > 0
hub_bonus       = +10 if note is in the top 10% by backlink count

Link Density Score = clamp(base_points + backlink_points + orphan_penalty + broken_penalty + hub_bonus, 0, 100)

Examples:

Metadata Completeness Score (Agent 3)

required_score    = (present_required_fields / total_required_fields)
recommended_score = (present_recommended_fields / total_recommended_fields) × 0.5
quality_bonus     = (present_quality_indicators / total_quality_indicators) × bonus_weight

Metadata Score = normalise_to_100(required_score + recommended_score + quality_bonus)

Required fields by type:

Quality indicators (ADRs only): confidence, freshness, source — 2 points each.

Structure Completeness Score (Agent 4)

ADR:     points_per_section = 20  (5 expected sections)
Meeting: points_per_section = 25  (4 expected sections)
Project: points_per_section = 33  (3 expected sections)
Concept: points_per_section = 25  (4 expected sections)
Other:   score = 100              (no structure requirement)

Structure Score = present_sections × points_per_section

Freshness Score (Agent 5)

freshness_points = 60 if fresh, 30 if recent, 0 if stale
tag_points       = (has_tags ? 20 : 0) + (optimal_count ? 20 : count_1 ? 10 : excessive ? 10 : 0)

Freshness Score = freshness_points + tag_points

Type-aware freshness thresholds:

Overall Quality Score

overallScore = readability × 0.20 + linkDensity × 0.25 + metadata × 0.20 + structure × 0.20 + freshness × 0.15

Output Format

# Vault Quality Report

**Date:** YYYY-MM-DD | **Scope:** <scope> | **Notes Analysed:** X

## Overall Score: X/100 (Grade: X)

| Dimension      | Score | Weight | Weighted |
|----------------|-------|--------|----------|
| Readability    | X/100 | 20%    | X        |
| Link Density   | X/100 | 25%    | X        |
| Metadata       | X/100 | 20%    | X        |
| Structure      | X/100 | 20%    | X        |
| Freshness      | X/100 | 15%    | X        |
| **Overall**    |       | 100%   | **X**    |

## Grade Distribution

| Grade | Count | Percentage |
|-------|-------|------------|
| A     | X     | X%         |
| B     | X     | X%         |
| C     | X     | X%         |
| D     | X     | X%         |
| F     | X     | X%         |

## Quality by Note Type

| Type     | Count | Avg Score | Lowest Score | Top Issue              |
|----------|-------|-----------|--------------|------------------------|
| ADR      | X     | X         | X            | <Most common issue>    |
| Meeting  | X     | X         | X            | <Most common issue>    |
| Concept  | X     | X         | X            | <Most common issue>    |

## Top X Issues (Prioritised)

| # | Note                  | Score | Grade | Primary Issue                | Fix                        |
|---|----------------------|-------|-------|------------------------------|----------------------------|
| 1 | <filename>           | X     | F     | Missing metadata + orphaned  | Add frontmatter, add links |
| 2 | <filename>           | X     | D     | Stale content, no summary    | Review and add summary     |

## Detailed Findings

### Orphaned Notes (X found)
<List of notes with 0 backlinks>

### Stale Notes (X found)
<Notes exceeding their type-specific freshness threshold>

### Missing Summaries (X found)
<Notes without `summary` field>

### Readability Concerns (X found)
<Notes with Flesch Reading Ease below 50>

## Recommendations

1. **Quick wins:** Add `summary` to X notes (improves metadata score by X points)
2. **Link building:** Connect X orphaned notes to related content
3. **Freshness:** Review X stale notes for accuracy

Examples

Example 1: Full Vault Report

/quality-report

Example 2: ADR Quality Check

/quality-report --type ADR --top-issues 10

Example 3: Folder-Specific Report

/quality-report --scope Projects/

Performance

• 5 parallel agents = approximately 5x faster than sequential analysis
• ~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 — consider excluding or adjusting weight for these
• Freshness scoring is type-aware: ADRs can be old and still valid, tasks go stale quickly
• Structure requirements are recommendations, not strict rules
• Link density considers both quality (backlinks from other notes) and quantity (outgoing links)
• Templates and system notes are excluded from scoring
• Can be run on subsets with --type or --scope filters

Invoke with: /quality-report to generate a comprehensive vault quality assessment