architecture-health

type	skill
lifecycle	stable
inheritance	inheritable
name	architecture-health
description	Diagnose cognitive architecture health — connection integrity, memory balance, link density, and drift detection
tier	standard
applyTo	**/*health*,**/*cognitive*,**/*drift*,**/*architecture*
currency	"2026-04-22T00:00:00.000Z"

Architecture Health Skill

Diagnose, don't describe. Every metric has a threshold. Every finding has a fix.

Health Dimensions

Dimension	What It Measures	Healthy	Warning	Critical
Connection Integrity	% of links targeting existing files	100%	95-99%	<95%
Connection Density	Avg connections per skill	3-6	1-2	0
Bidirectional Coverage	% of connections with reciprocal entries	>80%	50-80%	<50%
Memory Balance	Ratio of procedural:episodic:declarative	~1:1:4	Skewed 3:1	Missing category
Schema Compliance	Skills with valid frontmatter	100%	95-99%	<95%
Inheritance Consistency	Frontmatter inheritance matches catalog	100%	Any mismatch	—
Staleness	Skills with outdated content	<5%	5-15%	>15%

Diagnostic Patterns

Connection Integrity Check

Scan skill frontmatter applyTo patterns → verify referenced patterns have matching files.

Common breakage causes: File renames, folder restructuring, consolidation merges.

Fix pattern: Check consolidation mappings in dream-state-automation.instructions.md for old→new file paths. If not mapped, add the mapping and re-run dream.

Connection Density Analysis

orphan = skill with 0 connections (isolated node)
hub    = skill with 8+ connections (potential bottleneck)
leaf   = skill with 1 connection (normal for specialized skills)

Healthy network: Most skills are leaves (1-3) with a few hubs (meditation, self-actualization, memory-activation). Orphans indicate missing integration.

Memory Balance Assessment

Memory Type	File Pattern	Ideal %	Purpose
Declarative	SKILL.md, copilot-instructions.md	~60%	Domain knowledge
Procedural	.instructions.md	~25%	Auto-loaded procedures
Episodic	.prompt.md	~15%	Interactive workflows

Imbalance signals:

• Too many skills, few instructions → knows what but not how
• Too many instructions, few skills → follows steps but can't reason why
• Too few prompts → users can't invoke capabilities interactively

Drift Detection

Drift Type	Signal	Resolution
Version drift	package.json version ≠ copilot-instructions.md version	Sync via release-preflight
Terminology drift	Old terms ("DK files") in active files	Grep + replace
Count drift	Hardcoded numbers stale by next session	Replace with references
Inheritance drift	Catalog says "master-only" but frontmatter says "inheritable"	Trust frontmatter
Runtime loading drift	Skill/instruction exists on disk but doesn't load in agent	Use /troubleshoot to analyze JSONL debug logs — reveals name mismatches, invalid frontmatter, or silent loader skips

Health Report Template

## Architecture Health Report — [date]

### Summary: [HEALTHY | ATTENTION REQUIRED | CRITICAL]

| Dimension | Score | Status |
| --------- | ----- | ------ |
| Connection Integrity | X/Y valid (Z%) | ✅/⚠️/🔴 |
| Connection Density | avg N.N | ✅/⚠️/🔴 |
| Memory Balance | P:E:D = X:Y:Z | ✅/⚠️/🔴 |
| Schema Compliance | X/Y valid | ✅/⚠️/🔴 |

### Issues Found
1. [Issue] → [Fix]

Relationship to Other Systems

System	Role
Dream (muscle: brain-qa.cjs)	Automated structural checks — the "X-ray"
Architecture Health (this)	Interpretation framework — the "radiologist"
Meditation	Consolidation after diagnosis — the "surgery"
Self-Actualization	Comprehensive assessment — the "full physical"

Dream runs the scans. This skill teaches how to read and act on the results.

Triggers

• "health check", "connection health", "architecture health"
• "how's my brain?", "connection status"
• Before meditation (pre-assessment)
• After dream reports with warnings