health

Runtime Configuration (Step 0 — before any processing)

Read these files to configure domain-specific behavior:

1. ops/derivation-manifest.md — vocabulary mapping, folder names, platform hints

   • Use vocabulary.notes for the notes folder name
   • Use vocabulary.inbox for the inbox folder name
   • Use vocabulary.note for the note type name in output
   • Use vocabulary.topic_map for MOC/topic map references
   • Use vocabulary.topic_maps for plural form

2. ops/config.yaml — processing depth, thresholds

3. Three-space reference — ${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md for boundary rules (load only for full and three-space modes)

4. Templates — read template files to understand required schema fields for validation

If these files don’t exist (pre-init invocation or standalone use), use universal defaults:

• notes folder: notes/
• inbox folder: inbox/
• topic map: topic maps in notes/

EXECUTE NOW

Target: $ARGUMENTS

Parse the invocation mode immediately:

Execute these steps:

1. Detect mode from arguments
2. Scan the vault — inventory all note files, {vocabulary.topic_map} files, inbox items, ops files
3. Run each applicable diagnostic category in order (1-8)
4. Classify each result as PASS, WARN, or FAIL using the thresholds below
5. Surface condition-based maintenance signals (check against threshold table)
6. Generate the health report with specific file paths, counts, and recommended actions
7. Write report to ops/health/YYYY-MM-DD-report.md

START NOW. Reference below explains each diagnostic category in detail.

Platform Adaptation

Checks adapt to what the platform supports:

• If semantic search (qmd) is not configured, skip semantic-dependent checks and note their absence
• If hooks are not available, note that validation is convention-only (no automated enforcement)
• If self/ directory does not exist (disabled by config), skip self-space checks but verify ops/ absorbs self-space content correctly

Report what CAN be checked, not what the platform lacks.

The 8 Diagnostic Categories

Category 1: Schema Compliance (quick, full)

What it checks: Every {vocabulary.note} in {vocabulary.notes}/ and self/memory/ (if self/ is enabled) has valid YAML frontmatter with required fields.

How to check:

# Find all note files (exclude topic maps)
for f in {vocabulary.notes}/*.md; do
  [[ -f "$f" ]] || continue
  # Check: YAML frontmatter exists
  head -1 "$f" | grep -q '^---$' || echo "FAIL: $f — no YAML frontmatter"
  # Check: description field present
  rg -q '^description:' "$f" || echo "WARN: $f — missing description field"
  # Check: topics field present and links to at least one topic map
  rg -q '^topics:' "$f" || echo "WARN: $f — missing topics field"
done

Additional checks:

• Domain-specific enum fields have valid values (check against template _schema blocks if templates exist)
• description field is non-empty (not just present)
• topics field contains at least one wiki link

If validate-kernel.sh exists in ${CLAUDE_PLUGIN_ROOT}/reference/, run it and include results.

Thresholds:

Output format:

[1] Schema Compliance ............ WARN
    2 notes missing description:
      - notes/example-note.md
      - notes/another-note.md
    1 note missing topics:
      - notes/orphaned-claim.md
    12/15 notes fully compliant

Category 2: Orphan Detection (quick, full)

What it checks: Every {vocabulary.note} has at least one incoming wiki link from another file.

How to check:

# For each note file, check if ANY other file links to it
for f in {vocabulary.notes}/*.md; do
  [[ -f "$f" ]] || continue
  basename=$(basename "$f" .md)
  # Search for [[basename]] in all other files
  count=$(rg -l "\[\[$basename\]\]" --glob '*.md' | grep -v "$f" | wc -l | tr -d ' ')
  if [[ "$count" -eq 0 ]]; then
    echo "WARN: $f — no incoming links (orphan)"
  fi
done

Nuance: Orphans are not automatically failures. A note created today that hasn’t been through /{vocabulary.cmd_reflect} yet is expected to be orphaned temporarily. Check file age:

Output format:

[2] Orphan Detection ............. WARN
    3 orphan notes detected:
      - notes/new-claim.md (created 2h ago — awaiting reflect) [INFO]
      - notes/old-observation.md (created 5d ago) [WARN]
      - notes/forgotten-insight.md (created 14d ago) [FAIL]
    Recommendation: run /reflect on forgotten-insight.md and old-observation.md

Category 3: Link Health (quick, full)

What it checks: Every wiki link [[target]] in every file resolves to an existing file.

How to check:

# Extract all wiki links from all markdown files
# For each unique link target, verify a file with that name exists
rg -oN '\[\[([^\]]+)\]\]' --glob '*.md' -r '$1' | sort -u | while read target; do
  # Search for file matching this name
  found=$(find . -name "$target.md" -not -path "./.git/*" 2>/dev/null | head -1)
  if [[ -z "$found" ]]; then
    echo "FAIL: dangling link [[${target}]] — no file found"
    # Show which files contain this dangling link
    rg -l "\[\[$target\]\]" --glob '*.md'
  fi
done

Thresholds:

Why FAIL not WARN: Dangling links are broken promises. Every [[link]] a reader follows that leads nowhere erodes trust in the graph. Fix these immediately.

Output format:

[3] Link Health .................. FAIL
    2 dangling links found:
      - [[nonexistent-note]] referenced in:
        - notes/some-claim.md (line 14)
        - notes/another-claim.md (line 8)
      - [[removed-topic]] referenced in:
        - notes/old-note.md (line 22)
    Recommendation: create missing notes or remove broken links

Category 4: Description Quality (full only)

What it checks: Every {vocabulary.note}’s description adds genuine information beyond the title — not just a restatement.

How to check:

For each {vocabulary.note}:

1. Read the title (filename without extension)
2. Read the description field from YAML frontmatter
3. Evaluate: does the description add scope, mechanism, or implication that the title does not cover?

Quality heuristics:

Thresholds:

This check requires judgment. Use semantic understanding, not just string matching. A description that uses different words but says the same thing as the title is still a restatement.

Output format:

[4] Description Quality .......... WARN
    2 descriptions are restatements:
      - notes/quality-matters.md
        Title: "quality matters more than quantity"
        Description: "quality is more important than quantity in knowledge work"
        Issue: restates title without adding mechanism or implication
      - notes/structure-helps.md
        Title: "structure without processing provides no value"
        Description: "having structure without processing it is not valuable"
        Issue: exact restatement
    Recommendation: rewrite descriptions to add scope, mechanism, or implication

Category 5: Three-Space Boundary Check (full, three-space)

What it checks: Content respects the boundaries between self/, {vocabulary.notes}/, and ops/. Each space has a purpose — conflating them degrades search quality, navigation, and trust.

Before running this check: Read ${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md for the full boundary specification.

Six conflation patterns to detect:

5a. Ops into Notes (Infrastructure Creep)

Queue state, health metrics, task files, or processing artifacts appearing in {vocabulary.notes}/ directory.

Detection:

# Check for ops-pattern YAML fields in notes
rg '^(current_phase|completed_phases|batch|source_task|queue_id):' {vocabulary.notes}/ --glob '*.md'
# Check for task file patterns in notes
rg '## (Create|Reflect|Reweave|Verify|Enrich)$' {vocabulary.notes}/ --glob '*.md'

5b. Self into Notes (Identity Pollution)

Agent identity or methodology content mixed into user’s knowledge graph. Agent’s operational observations appearing in user’s {vocabulary.notes}/ space.

Detection:

# Check for agent-reflection patterns in notes (methodology observations, workflow assessments)
rg -i '(my methodology|I observed that|agent reflection|session learning|I learned)' {vocabulary.notes}/ --glob '*.md'

5c. Notes into Ops (Trapped Knowledge)

Genuine insights trapped in session logs, observations, or ops files that should be promoted to {vocabulary.notes}/.

Detection:

# Check for claim-like content in ops that could be notes
# Look for files with description fields in ops/observations/ or ops/methodology/
rg '^description:' ops/observations/*.md ops/methodology/*.md 2>/dev/null

5d. Self into Ops / Ops into Self

Temporal state stored in self/ (should be in ops/), or identity content stored in ops/ (should be in self/).

Detection:

# Check for temporal/queue content in self/
rg '^(current_phase|status|queue):' self/ --glob '*.md' 2>/dev/null
# Check for identity content in ops/
rg -i '(my identity|I am|who I am|my personality)' ops/ --glob '*.md' 2>/dev/null

5e. Notes into Self

Domain knowledge stored in self/ instead of {vocabulary.notes}/.

Detection:

# Check self/memory/ for notes that have topics linking to notes-space topic maps
rg '^topics:.*\[\[' self/memory/*.md 2>/dev/null | grep -v 'identity\|methodology\|goals\|relationships'

5f. Self Space Absence Effects (when self/ is disabled)

When self/ is disabled, verify ops/ absorbs self-space content correctly. Check that goals and handoffs are in ops/, not floating in {vocabulary.notes}/.

Detection:

# If self/ doesn't exist, check that goals/handoffs are in ops/
if [[ ! -d "self/" ]]; then
  # Check for goals or handoff content in notes/
  rg -i '(my goals|current goals|handoff|session handoff)' {vocabulary.notes}/ --glob '*.md'
fi

Thresholds:

Output format:

[5] Three-Space Boundaries ....... WARN
    1 boundary violation detected:
      Ops into Notes (infrastructure creep):
        - notes/task-tracking.md contains queue state fields (current_phase, batch)
        - Should be in ops/queue/ not notes/
    1 potential trapped knowledge:
      - ops/observations/interesting-pattern.md has note-like schema
        Consider promoting to notes/ via /reduce or direct creation
    Recommendation: move task-tracking.md to ops/queue/

Category 6: Processing Throughput (full only)

What it checks: The inbox-to-knowledge ratio. High ratios indicate collector’s fallacy — capturing more than processing.

How to check:

# Count items in each space
INBOX_COUNT=$(find {vocabulary.inbox}/ -name '*.md' -not -path '*/archive/*' 2>/dev/null | wc -l | tr -d ' ')
NOTES_COUNT=$(find {vocabulary.notes}/ -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
QUEUE_COUNT=$(find ops/queue/ -name '*.md' -not -path '*/archive/*' 2>/dev/null | wc -l | tr -d ' ')

# Calculate ratio
if [[ $((INBOX_COUNT + NOTES_COUNT)) -gt 0 ]]; then
  RATIO=$((INBOX_COUNT * 100 / (INBOX_COUNT + NOTES_COUNT)))
else
  RATIO=0
fi

echo "Inbox: $INBOX_COUNT | Notes: $NOTES_COUNT | In-progress: $QUEUE_COUNT | Ratio: ${RATIO}%"

Thresholds:

Output format:

[6] Processing Throughput ........ WARN
    inbox: 12 | notes: 8 | in-progress: 3 | ratio: 60%
    Inbox items outnumber processed notes — collector's fallacy risk
    Recommendation: run /reduce on oldest inbox items or /pipeline for end-to-end processing

Category 7: Stale Note Detection (full only)

What it checks: Notes not modified recently AND with low link density. Staleness is condition-based (low link density + no activity since N new notes were added), not purely calendar-based.

How to check:

For each {vocabulary.note}:

1. Check last modified date (stat or git log)
2. Count incoming links (same as orphan detection, but counting instead of boolean)
3. Flag notes with: modified > 30 days ago AND < 2 incoming links

for f in {vocabulary.notes}/*.md; do
  [[ -f "$f" ]] || continue
  basename=$(basename "$f" .md)

  # Last modified (days ago)
  mod_days=$(( ($(date +%s) - $(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null)) / 86400 ))

  # Incoming link count
  incoming=$(rg -l "\[\[$basename\]\]" --glob '*.md' | grep -v "$f" | wc -l | tr -d ' ')

  if [[ $mod_days -gt 30 ]] && [[ $incoming -lt 2 ]]; then
    echo "STALE: $f — $mod_days days old, $incoming incoming links"
  fi
done

Thresholds:

Prioritization: Sort stale notes by:

1. Age (oldest first)
2. Link density (least connected first)
3. Topic relevance (notes in active topic areas are higher priority)

Output format:

[7] Stale Notes .................. WARN
    4 stale notes detected (>30d old, <2 incoming links):
      - notes/old-observation.md (92d, 0 links) [FAIL — consider archiving or reweaving]
      - notes/early-claim.md (45d, 1 link) [WARN]
      - notes/setupial-thought.md (38d, 1 link) [WARN]
      - notes/first-draft.md (31d, 0 links) [WARN]
    Recommendation: run /reweave on these notes to find connections, or archive if no longer relevant

Category 8: {vocabulary.topic_map} Coherence (full only)

What it checks: Each {vocabulary.topic_map} has a healthy number of linked notes, and notes in the same topic area are actually linked.

How to check:

For each {vocabulary.topic_map} file:

1. Count notes that link TO this {vocabulary.topic_map} (notes with this in their topics footer/field)
2. Check if there are notes in the same topic area NOT linked to the {vocabulary.topic_map} (coverage gaps)
3. Verify context phrases exist on Core Ideas links (not bare links)

# For each topic map
for moc in {vocabulary.notes}/*.md; do
  [[ -f "$moc" ]] || continue
  # Check if this is a topic map (has type: moc in frontmatter)
  rg -q '^type: moc' "$moc" || continue

  moc_name=$(basename "$moc" .md)

  # Count notes linking to this topic map
  note_count=$(rg -l "\[\[$moc_name\]\]" {vocabulary.notes}/ --glob '*.md' | grep -v "$moc" | wc -l | tr -d ' ')

  echo "$moc_name: $note_count notes"
done

Thresholds:

Context phrase check:

# Check for bare links in topic map Core Ideas (links without context phrases)
for moc in {vocabulary.notes}/*.md; do
  rg -q '^type: moc' "$moc" || continue
  # Look for "- [[note]]" without " — " context
  rg '^\s*- \[\[' "$moc" | grep -v ' — ' | grep -v '^\s*- \[\[.*\]\].*—'
done

Bare links without context phrases are address book entries, not navigation. Every link in a {vocabulary.topic_map} should explain WHY to follow it.

Output format:

[8] MOC Coherence ................ WARN
    3 topic maps checked:
      - knowledge-work: 28 notes [PASS]
      - graph-structure: 52 notes [WARN — oversized, consider splitting]
        3 bare links without context phrases
      - agent-cognition: 3 notes [WARN — underdeveloped, consider merging]
    Recommendation: split graph-structure into sub-topic-maps; add context phrases to bare links

Condition-Based Maintenance Signals

After running all applicable diagnostic categories, check these condition-based triggers. These are NOT the 8 categories above — they are cross-cutting signals that suggest specific skill invocations.

How to check condition counts:

# Pending observations
OBS_COUNT=$(find ops/observations/ -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

# Open tensions
TENSION_COUNT=$(find ops/tensions/ -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

# Inbox items
INBOX_COUNT=$(find {vocabulary.inbox}/ -name '*.md' -not -path '*/archive/*' 2>/dev/null | wc -l | tr -d ' ')

# Unprocessed sessions
SESSION_COUNT=$(find ops/sessions/ -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

# Queue stalled
PENDING_TASKS=$(jq '[.tasks[] | select(.status=="pending")] | length' ops/queue/queue.json 2>/dev/null || echo 0)

The meta-trigger: Include a “trigger coverage” check. Compare known maintenance conditions against what is actually being checked. If a maintenance condition has no corresponding check or trigger configured, that gap itself is a finding. This prevents the failure mode where maintenance debt accumulates undetected.

Output Format

The complete health report follows this structure. Every report, regardless of mode, uses this format.

=== HEALTH REPORT ===
Mode: [quick | full | three-space]
Date: YYYY-MM-DD
Notes scanned: N | Topic maps: N | Inbox items: N

Summary: N FAIL, N WARN, N PASS

FAIL:
- [Category N]: [brief description of failure]
  [specific files and details]

WARN:
- [Category N]: [brief description of warning]
  [specific files and details]

PASS:
- [Category N]: [confirmation]

---

[1] Schema Compliance ............ PASS | WARN | FAIL
    [details — specific files, specific issues]

[2] Orphan Detection ............. PASS | WARN | FAIL
    [details — specific files, age, link count]

[3] Link Health .................. PASS | WARN | FAIL
    [details — specific dangling links, where referenced]

[4] Description Quality .......... PASS | WARN | FAIL  (full mode only)
    [details — specific files, title vs description comparison]

[5] Three-Space Boundaries ....... PASS | WARN | FAIL  (full/three-space mode)
    [details — specific boundary violations by type]

[6] Processing Throughput ........ PASS | WARN | FAIL  (full mode only)
    inbox: N | notes: N | in-progress: N | ratio: N%

[7] Stale Notes .................. PASS | WARN | FAIL  (full mode only)
    [N notes older than 30d with <2 incoming links, sorted by priority]

[8] MOC Coherence ................ PASS | WARN | FAIL  (full mode only)
    [details — note count per topic map, coverage gaps, bare links]

---

Maintenance Signals:
    [condition-based triggers from table above, if any thresholds met]
    - observations: N pending (threshold: 10) [TRIGGERED | OK]
    - tensions: N pending (threshold: 5) [TRIGGERED | OK]
    - inbox: N items (threshold: 3) [TRIGGERED | OK]
    - sessions: N unprocessed (threshold: 5) [TRIGGERED | OK]

---

Recommended Actions (top 3, ranked by impact):
1. [Most impactful action — specific command + specific file]
2. [Second priority — specific command + specific file]
3. [Third priority — specific command + specific file]
=== END REPORT ===

Report Storage

Write every health report to ops/health/YYYY-MM-DD-report.md. If multiple reports are run on the same day, append a counter: YYYY-MM-DD-report-2.md.

This creates a health history that /architect can reference when proposing evolution. Trends across reports reveal systemic patterns that individual reports miss.

Quality Standards

Be Specific

Every finding MUST name the specific file(s) involved.

Bad: “some notes lack descriptions” Good: “notes/example-note.md and notes/another-note.md are missing the description field”

Bad: “there are dangling links” Good: “[[nonexistent-claim]] is referenced in notes/old-note.md (line 14) and notes/related.md (line 22) but no file with that name exists”

Prioritize by Impact

Not all issues are equal. The recommended actions section ranks by impact:

Don’t Overwhelm

• Focus on the top 5-10 issues in the recommended actions
• Group related issues (3 notes missing descriptions = 1 finding, not 3)
• For large vaults, cap per-category detail at 10 specific files, then summarize: “…and 15 more”

Distinguish FAIL from WARN

FAIL is reserved for: Dangling links (broken graph), persistent orphans (> 7 days), severe schema violations (missing frontmatter entirely), critical boundary violations.

WARN is for everything else that is suboptimal but not broken.

Mode-Specific Behavior

Quick Mode (default)

Runs categories 1-3 only: Schema, Orphans, Links.

Use when:

• Session start health check
• Quick pulse on vault integrity
• After a batch of note creation

Runtime: Should complete in < 30 seconds for vaults up to 200 notes.

Full Mode

Runs all 8 categories plus maintenance signals.

Use when:

• Periodic comprehensive health review
• After significant vault changes (large batch processing, restructuring)
• When something “feels wrong” about the vault
• Before a /architect or /reseed session

Runtime: May take 1-3 minutes for larger vaults due to description quality analysis and {vocabulary.topic_map} coherence checks.

Three-Space Mode

Runs category 5 only: boundary violation checks.

Use when:

• After /reseed to verify boundaries are intact
• When search results seem contaminated (ops content in knowledge queries)
• When self/ is being enabled or disabled
• Debugging “why does my search return weird results?”

Runtime: Should complete in < 30 seconds.

Edge Cases

Empty Vault

A vault with 0 notes is not unhealthy — it is new. Report:

Notes scanned: 0 | Topic maps: 0 | Inbox items: N
All categories PASS (no notes to check)
Maintenance Signal: inbox has N items — consider /reduce to start building knowledge

Self Space Disabled

When self/ does not exist:

• Skip self-space boundary checks (5b, 5d, 5e inbound)
• But DO check that ops/ correctly absorbs self-space content (5f)
• Note in the report: “self/ is disabled — boundary checks adapted accordingly”

No Semantic Search

When qmd/MCP tools are unavailable:

• Skip any checks that depend on semantic search
• Note in the report: “Semantic search unavailable — some checks skipped”
• All file-based checks (schema, orphans, links, boundaries) still run

Large Vaults (500+ notes)

• Cap per-category file listings at 10, then summarize
• Consider running checks in batches if performance degrades
• Focus recommended actions on highest-impact items

Integration with Other Skills

Health report findings feed into other skills:

The health-to-action loop:

/health (diagnose) -> specific findings -> specific skill invocation -> /health (verify fix)

Health is diagnostic only — it measures state without prescribing changes. /architect reads health reports and proposes changes with research backing. The separation matters: health tells you WHAT is wrong, architect tells you WHY and HOW to fix it.