brain-qa

name	brain-qa
description
tier	standard Semantic, logic, code, and architectural validation of Alex's cognitive architecture — not just file counts, but meaning coherence
disable-model-invocation	true
applyTo	**/*skill*,**/*trigger*,**/*brain*,**/*qa*
currency	2026-04-22T00:00:00.000Z

Brain QA

Semantic, logic, code, and architectural validation of Alex's cognitive architecture — not just file counts, but meaning coherence

Philosophy

Brain QA is a mental exercise, not just a muscle exercise. The script validates structure, but the skill's true value is teaching Alex what to look for beyond what scripts can automate.

A single script serves both master and heir contexts:

Script	Context	Behavior	Inheritance
brain-qa.cjs	Master	Full grid with master-only skill detection	inheritable
brain-qa.cjs	Heir	Same grid, master-only features degrade gracefully	inheritable

The script auto-detects context: if sync-architecture.cjs exists, it reads master-only skill exclusions. In heirs (where that file is absent), it returns an empty set and all skills are treated equally.

Dimension	Script Catches	Alex Catches (with this skill)
Structural	Missing files, broken paths, count mismatches	✅ Automated
Semantic	—	Terminology drift (e.g. "DK files" vs "skills"), meaning contradictions between documents
Logic	—	Process descriptions that conflict (e.g. dream says X, meditation says Y), impossible workflows
Code	Compile errors, lint	Code behavior diverging from documented claims (e.g. documented trigger not wired in TypeScript)
Architectural	—	Working memory model inconsistencies, neuroanatomical mappings that contradict instruction files

Rule: When running brain-qa, always pair the script output with a semantic review. The script is the body; this skill is the brain.

Quick Start

Run

# Generate brain health grid
node .github/muscles/brain-qa.cjs

The output is written to .github/quality/brain-health-grid.md.

When to Use

• Before releases (structural + semantic review)
• After adding/modifying skills (do new connections make logical sense?)
• After bulk connection updates (are links semantically meaningful?)
• When trigger conflicts are suspected (logic: can two triggers fire contradictory protocols?)
• To verify Master-Heir parity (architectural: does heir behavior match master docs?)
• To validate LLM-friendly content formats
• After any documentation refactor — check that meaning didn't drift when words changed
• When code and docs diverge — documented feature doesn't match TypeScript implementation
• When skills/instructions don't load at runtime — use /troubleshoot in chat to analyze agent debug logs (requires github.copilot.chat.agentDebugLog.enabled)

Audit Phases

Phase	Name	Validates	Heir?
1	Connection Target Validation	All connection targets exist	Yes
2	Inheritance Field Validation	All skills have inheritance field	Yes
3	Skill Index Coverage	All skills in memory-activation index	Yes
4	Trigger Semantic Analysis	Overlapping keywords (warnings OK if related)	Yes
5	Master-Heir Skill Sync	Skill directories match	No
6	Connection Schema Format	Valid frontmatter, applyTo present	Yes
7	Connection File Sync	Skill file hash match	No
8	Memory-Activation Index Sync	SKILL.md hash match	No
9	(retired)	(catalogs removed — use brain-health-grid)	—
10	Core File Token Budget	Size + ASCII art checks on core files	Yes
11	Boilerplate Descriptions	No placeholder skill descriptions	Yes
12	Heir Reset Validation	Empty profile, available P5-P7 slots	Yes
13	Instructions/Prompts Sync	Memory files synced to heir	No
14	Agents Structure	Valid agent files in both	Yes
15	Config Files	Required configs present, no leaks	Yes
16	Skill YAML Frontmatter	name and description in frontmatter	Yes
17	Internal Skills Hidden	user-invokable: false for metacognition	Yes
18	Agent Handoffs	Return-to-Alex handoffs present	Yes
19	ApplyTo Patterns	Instructions have file-type patterns	Yes
20	LLM-First Content

Mode Shortcuts

Mode	Phases	Use Case
all	1-31	Full audit before release
quick	1-6	Fast validation during development
sync	5,7,8,13-15,27,28	Master-Heir synchronization check
schema	2,6,11,16,17	Schema, frontmatter, and format validation
llm	10,20,21	LLM-first content format validation
ghfolder	22-25	.github/ subfolder health
full	26-31	External folders + cross-repo validation

Known Gaps (Future Phases)

Phase	Name	Validates
22	Brain HTML Count Drift	Hardcoded counts in docs/alex-brain-anatomy.html match actual file counts (skills, instructions, muscles, prompts)
23	Motor Cortex Mapping	Muscle inventory in brain diagrams matches .github/muscles/

Context: Session 2026-02-13 discovered stale counts in brain HTML (muscles 13→11, procedures 29→28, skills 100+→116). Diagrams with hardcoded numbers will drift after any architecture change.

Common Issues

Issue	Fix
Broken connection target	Update path in frontmatter or body links
Missing from heir	Check SKILL_EXCLUSIONS in sync-architecture.cjs
Out of sync	Run with -Fix or use build-extension-package.cjs
Boilerplate description	Write meaningful description in SKILL.md frontmatter
Master-only leak	Remove protected files from heir
Missing YAML frontmatter	Add ---\nname:\ndescription:\n--- to SKILL.md
ASCII art warning	Replace with Mermaid diagrams or tables
Missing return-to-Alex	Add handoff to main Alex agent
Brain HTML count drift	Update hardcoded numbers in docs/alex-brain-anatomy.html
Incomplete connection	Use full path: .github/skills/name/SKILL.md not name
Missing applyTo pattern	Add applyTo: to SKILL.md frontmatter
Master-heir ref mismatch	Remove master-only files (ROADMAP.md) from heir

Iterative Validation Workflow

When repairing architecture issues, use this proven pattern:

1. Audit → Run brain-qa phase to identify errors
2. Fix Errors → Address primary issues (paths, references)
3. Re-validate → Run same phase to verify fixes
4. Fix Schema → Address structural issues ($schema, inheritance)
5. Final Check → Run quick mode to verify all phases pass

Example from 2026-02-15 session:

• Phase 1 failed → Fixed incomplete connection paths → Phase 1 passed
• Phase 6 failed → Added applyTo patterns → Phase 6 passed
• Phase 7 warned about sync differences → Expected after manual edits, auto-resolves at publish

Key principle: Iterative validation catches cascading errors before they compound. Each phase builds on previous fixes.

Semantic Review Checklist (Manual — Not Scriptable)

After running the script, Alex should check:

• Cross-document meaning: Do copilot-instructions, alex-core, and protocol-triggers describe the same processes consistently?
• Working memory model: Does the 4+3 slot claim match the actual P1-P7 table? Are sub-slots (P4a-d) accounted for?
• Legacy terminology: Any surviving references to deprecated concepts (DK files, domain-knowledge folders)?
• Trigger-to-code alignment: Do trigger keywords in .md files match actual activation paths in TypeScript?
• Heir evolution logic: Does the documented 4-step heir cycle match what heir-skill-promotion.instructions.md actually describes?
• Version source of truth: Is package.json the single source, or are versions hardcoded in prose that will drift?
• Neuroanatomical consistency: Do brain-analog mappings in copilot-instructions match descriptions in alex-core?

Integration

• Dream Protocol: Run brain-qa after dream for deeper analysis
• Release Preflight: Include -Mode quick in release checks
• LLM Content Audit: Run -Mode llm when updating diagrams
• Skill Selection Optimization: Brain QA validates SSO data sources
• Semantic Audit: Pair script output with manual checklist above — script validates structure, Alex validates meaning

Architecture Health Diagnostics

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

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%
Staleness	Skills with outdated content	<5%	5-15%	>15%

Diagnostic Patterns

Connection Integrity: Parse skill frontmatter → verify applyTo patterns have matching files. Common breakage: file renames, consolidation merges.

Connection Density: orphan = 0 connections (isolated), hub = 8+ connections (bottleneck), leaf = 1-3 (normal).

Memory Balance: Declarative (SKILL.md) ~60%, Procedural (.instructions.md) ~25%, Episodic (.prompt.md) ~15%. Too many skills + few instructions = knows what but not how.

Drift Detection

Drift Type	Signal	Resolution
Version drift	package.json ≠ copilot-instructions.md	Sync via release-preflight
Terminology drift	Old terms in active files	Grep + replace
Count drift	Hardcoded numbers stale	Replace with references
Inheritance drift	Catalog vs sync exclusions mismatch	Trust SKILL_EXCLUSIONS in sync-architecture.cjs

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      | ✅/⚠️/🔴 |

Triggers

• "brain qa", "brain audit", "validate brain"
• "connection audit", "deep connection check"
• "health check", "connection health", "architecture health"
• "master heir sync", "heir sync validation"
• "catalog validation", "instruction sync"
• "semantic audit", "logic check", "meaning consistency"

---

Script: .github/muscles/brain-qa.cjs