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	**/*synapse*,**/*skill*,**/*trigger*

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.

Two scripts serve different contexts:

Script	Context	Phases	Inheritance
brain-qa.ps1	Master Alex	31 (full)	master-only
brain-qa-heir.ps1	Heir deployments	23 (heir-relevant)	inheritable

During sync, brain-qa-heir.ps1 is renamed to brain-qa.ps1 in the heir, so all contexts use the same filename. The master version includes cross-repo sync phases (5, 7, 8, 13) and master-only validations (26-29) that don't apply to heirs.

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

Master Context

# Full 31-phase audit
.github/muscles/brain-qa.ps1

# Quick validation (phases 1-6)
.github/muscles/brain-qa.ps1 -Mode quick

# Sync validation only (phases 5,7,8,13,14,15,27,28)
.github/muscles/brain-qa.ps1 -Mode sync

# Schema/frontmatter validation (phases 2,6,11,16,17)
.github/muscles/brain-qa.ps1 -Mode schema

# LLM-first content validation (phases 10,20,21)
.github/muscles/brain-qa.ps1 -Mode llm

# Specific phases
.github/muscles/brain-qa.ps1 -Phase 1,5,7

# Auto-fix sync issues
.github/muscles/brain-qa.ps1 -Mode sync -Fix

Heir Context

# Full heir audit (23 heir-relevant phases)
.github/muscles/brain-qa.ps1

# Quick validation (phases 1-4,6)
.github/muscles/brain-qa.ps1 -Mode quick

# Schema/frontmatter validation (phases 2,6,11,16,17)
.github/muscles/brain-qa.ps1 -Mode schema

# LLM content validation (phases 10,20,21)
.github/muscles/brain-qa.ps1 -Mode llm

# Note: -Mode sync is not available in heir (sync phases are master-only)

When to Use

• Before releases (structural + semantic review)
• After adding/modifying skills (do new synapses make logical sense?)
• After bulk synapse updates (are connections 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	Synapse 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	Synapse Schema Format	Numeric strengths, $schema present	Yes
7	Synapse File Sync	synapses.json hash match	No
8	Memory-Activation Index Sync	SKILL.md hash match	No
9	Catalog Accuracy	SKILLS-CATALOG count matches reality	Yes (count-only)
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	No ASCII art, Mermaid OK

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 synapse target	Update path in synapses.json
Missing from heir	Check SKILL_EXCLUSIONS in sync-architecture.cjs
Out of sync	Run with -Fix or use build-extension-package.ps1
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 synapse path	Use full path: .github/skills/name/SKILL.md not name
Missing $schema property	Add "$schema": "../SYNAPSE-SCHEMA.json" to synapses.json
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 synapse paths → Phase 1 passed
• Phase 6 failed → Added $schema properties → 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 synapse 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
Synapse Integrity	% of connections 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 synapses.json	100%	95-99%	<95%
Staleness	Skills with outdated content	<5%	5-15%	>15%

Diagnostic Patterns

Synapse Integrity: Parse synapses.json → extract connections[].target → verify file exists. 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   |
| ------------------ | -------------- | -------- |
| Synapse 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"
• "synapse audit", "deep synapse check"
• "health check", "synapse health", "architecture health"
• "master heir sync", "heir sync validation"
• "catalog validation", "instruction sync"
• "semantic audit", "logic check", "meaning consistency"

---

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