| name | Brain QA |
| description | 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
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:
| 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
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 | Yes |
| 21 | Emoji Semantics | Meaningful emoji usage stats | Yes |
| 22 | Episodic Archive Health | .github/episodic/ session records valid | Yes |
| 23 | Assets Validation | .github/assets/ contains expected files | Yes |
| 24 | Issue/PR Templates | GitHub templates present and valid | Yes |
| 25 | Root File Completeness | Required .github/ root files exist | Yes |
| 26 | alex_docs Freshness | Documentation not stale beyond threshold | No |
| 27 | M365 Heir Validation | M365 heir structure and version alignment | No |
| 28 | Codespaces Heir Validation | Codespaces devcontainer and config valid | No |
| 29 | Global Knowledge Sync | GK repo index and counts consistent | No |
| 30 | Muscles Integrity | All scripts referenced by trifectas exist | Yes |
| 31 | ROADMAP Version Alignment | ROADMAP versions match package.json | Yes (config-only) |
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-UNIFIED.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:
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
