arscontexta 0.6.0

package/skills/health/SKILL.md

@@ -0,0 +1,760 @@
+---
+name: health
+description: Run condition-based vault health diagnostics. 8 categories — schema compliance, orphan detection, link health, description quality, three-space boundaries, processing throughput, stale notes, MOC coherence. 3 modes — quick (schema+orphans+links), full (all 8), three-space (boundary violations only). Returns actionable FAIL/WARN/PASS report with specific fixes ranked by impact. Triggers on "/health", "check vault health", "maintenance report", "what needs fixing".
+version: "1.0"
+generated_from: "arscontexta-v1.6"
+context: fork
+model: opus
+allowed-tools: Read, Grep, Glob, Bash, mcp__qmd__vsearch
+argument-hint: "[optional: 'quick', 'full', or 'three-space']"
+---
+
+## 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:
+
+| Input | Mode | Categories Run |
+|-------|------|---------------|
+| empty or `quick` | Quick | 1 (Schema), 2 (Orphans), 3 (Links) |
+| `full` | Full | All 8 categories |
+| `three-space` | Three-Space | 5 (Three-Space Boundaries) only |
+
+**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:**
+
+```bash
+# 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:**
+
+| Condition | Level |
+|-----------|-------|
+| Any note missing YAML frontmatter | FAIL |
+| Any note missing `description` field | WARN |
+| Any note missing `topics` field | WARN |
+| Any invalid enum value | WARN |
+| All notes pass all checks | PASS |
+
+**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:**
+
+```bash
+# 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:
+
+| Condition | Level |
+|-----------|-------|
+| Orphan note created < 24 hours ago | INFO (expected — awaiting reflect phase) |
+| Orphan note created 1-7 days ago | WARN |
+| Orphan note older than 7 days | FAIL (persistent orphan needs attention) |
+| No orphans detected | PASS |
+
+**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:**
+
+```bash
+# 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:**
+
+| Condition | Level |
+|-----------|-------|
+| Any dangling link (target does not exist) | FAIL |
+| All links resolve | PASS |
+
+**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:**
+
+| Check | Threshold |
+|-------|-----------|
+| Description length | 50-200 chars ideal. < 30 chars = too terse. > 250 chars = too verbose |
+| Restatement detection | If description uses >70% of the same words as the title = restatement |
+| Information added | Description should mention mechanism, scope, or implication not in title |
+
+**Thresholds:**
+
+| Condition | Level |
+|-----------|-------|
+| Description is a clear restatement of the title | WARN |
+| Description is < 30 characters | WARN |
+| Description is missing entirely | WARN (also caught by Category 1) |
+| Description adds genuine new information | PASS |
+
+**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:**
+```bash
+# 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'
+```
+
+| Found | Level |
+|-------|-------|
+| Any ops-pattern content in {vocabulary.notes}/ | WARN |
+
+#### 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:**
+```bash
+# 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'
+```
+
+| Found | Level |
+|-------|-------|
+| Any agent-reflection content in {vocabulary.notes}/ | WARN |
+
+#### 5c. Notes into Ops (Trapped Knowledge)
+
+Genuine insights trapped in session logs, observations, or ops files that should be promoted to {vocabulary.notes}/.
+
+**Detection:**
+```bash
+# 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
+```
+
+| Found | Level |
+|-------|-------|
+| Content in ops/ with note-like schema (description + topics) | INFO (may be intentional, flag for review) |
+
+#### 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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:**
+
+| Condition | Level |
+|-----------|-------|
+| Any boundary violation (5a, 5b, 5d, 5e) | WARN |
+| Trapped knowledge in ops (5c) | INFO |
+| Self-absence effects (5f) | WARN |
+| All boundaries intact | PASS |
+
+**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:**
+
+```bash
+# 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:**
+
+| Condition | Level |
+|-----------|-------|
+| Inbox-to-total ratio > 75% (3:1 inbox to notes) | FAIL |
+| Inbox-to-total ratio > 50% | WARN |
+| Inbox items > 20 | WARN (regardless of ratio) |
+| Inbox-to-total ratio <= 50% AND inbox <= 20 | PASS |
+
+**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
+
+```bash
+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:**
+
+| Condition | Level |
+|-----------|-------|
+| Any note > 30 days old with < 2 incoming links | WARN |
+| Any note > 90 days old with 0 incoming links | FAIL |
+| All notes either recent or well-connected | PASS |
+
+**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)
+
+```bash
+# 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:**
+
+| Condition | Level |
+|-----------|-------|
+| {vocabulary.topic_map} with < 5 notes | WARN (underdeveloped — consider merging into parent) |
+| {vocabulary.topic_map} with > 50 notes | WARN (oversized — consider splitting into sub-{vocabulary.topic_maps}) |
+| {vocabulary.topic_map} with > 40 notes | INFO (approaching threshold) |
+| Notes exist in topic area but not linked to {vocabulary.topic_map} | WARN (coverage gap) |
+| All {vocabulary.topic_maps} in 5-50 range with good coverage | PASS |
+
+**Context phrase check:**
+
+```bash
+# 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.
+
+| Condition | Threshold | Recommendation |
+|-----------|-----------|---------------|
+| Pending observations | >= 10 files in ops/observations/ | Consider running /rethink |
+| Open tensions | >= 5 files in ops/tensions/ | Consider running /rethink |
+| Inbox items | >= 3 items | Consider /reduce or /pipeline |
+| Unprocessed sessions | >= 5 files in ops/sessions/ | Consider /remember --mine-sessions |
+| Orphan notes | Any persistent (> 7d) | Run /reflect on orphaned notes |
+| Dangling links | Any | Fix broken references immediately |
+| Stale notes | Low links + old | Consider /reweave |
+| {vocabulary.topic_map} oversized | > 40 notes | Consider splitting |
+| Queue stalled | Tasks pending > 2 sessions without progress | Surface as blocked |
+| Trigger coverage gap | Known maintenance condition has no configured trigger | Flag gap itself |
+
+**How to check condition counts:**
+
+```bash
+# 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:
+
+| Impact Tier | Examples | Why |
+|------------|---------|-----|
+| Highest | Dangling links, persistent orphans | Broken promises in the graph — readers hit dead ends |
+| High | Schema violations, boundary violations | Structural integrity — compounds into larger problems |
+| Medium | Description quality, stale notes | Retrieval quality — degraded but not broken |
+| Low | {vocabulary.topic_map} size warnings, throughput ratio | Maintenance debt — matters at scale |
+
+### 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
+
+| Level | Meaning | Action Required |
+|-------|---------|----------------|
+| FAIL | Structural issue — something is broken | Fix before it compounds |
+| WARN | Improvement opportunity — something is suboptimal | Address when convenient |
+| PASS | Category is healthy | No action needed |
+| INFO | Noteworthy but not actionable | Context for understanding |
+
+**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:
+
+| Finding | Feeds Into | How |
+|---------|-----------|-----|
+| Orphan notes | /reflect | Run reflect to find connections for orphaned notes |
+| Stale notes | /reweave | Run reweave to update old notes with new connections |
+| Description quality issues | /verify or manual rewrite | Fix descriptions to improve retrieval |
+| Schema violations | /validate | Run validation to fix specific schema issues |
+| Boundary violations | Manual restructuring | Move files to correct space |
+| Processing throughput | /reduce or /pipeline | Process inbox items to improve ratio |
+| {vocabulary.topic_map} oversized | Manual split or /architect | Split oversized {vocabulary.topic_maps} into sub-{vocabulary.topic_maps} |
+| Accumulated observations | /rethink | Review and triage observations |
+| Accumulated tensions | /rethink | Resolve or dissolve tensions |
+
+**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.