Brain QA

Brain QA

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

Synapses

Format: See SYNAPSE-SCHEMA.md for notation reference

• [.github/instructions/semantic-audit.instructions.md] (High, Coordinates, Bidirectional) - "Procedural memory for manual semantic review that complements automated brain-qa"
• [.github/instructions/cognitive-health-validation.instructions.md] (Critical, Coordinates, Bidirectional) - "Comprehensive brain-qa integration with meditation and release workflows"
• [.github/skills/architecture-audit/SKILL.md] (Medium, Related, Bidirectional) - "Full repository/project audit including brain-qa execution"
• [.github/instructions/dream-state-automation.instructions.md] (Medium, Complements, Forward) - "Dream validates synapses, brain-qa validates structure"
• [.github/instructions/release-management.instructions.md] (High, Gates, Forward) - "Pre-release validation requires brain-qa passing"

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:

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.

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

Audit Phases

Mode Shortcuts

Known Gaps (Future Phases)

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

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

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

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