Menu
Semantic, logic, code, and architectural validation of Alex's cognitive architecture — not just file counts, but meaning coherence
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Defense-in-depth, PII protection, secrets scanning, and secure packaging for distributed software
Systematic testing for confidence without over-testing — the right test at the right level
Generate consistent visual character references across multiple scenarios using Flux and nano-banana-pro on Replicate
Create professional ultra-wide cinematic banners for GitHub READMEs using Flux and Ideogram models with typography options
Generate professional presentations using the Gamma API with expert storytelling consulting based on Duarte methodology.
Intelligent project persona identification using priority chain detection with LLM and heuristic fallback
| name | Brain QA |
| description | Semantic, logic, code, and architectural validation of Alex's cognitive architecture — not just file counts, but meaning coherence |
| applyTo | **/*synapse*,**/*skill*,**/*trigger* |
Semantic, logic, code, and architectural validation of Alex's cognitive architecture — not just file counts, but meaning coherence
Format: See SYNAPSE-SCHEMA.md for notation reference
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.
# 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
# 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)
| 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 skill-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 | Skill-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 | 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 |
| 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.
| Issue | Fix |
|---|---|
| Broken synapse target | Update path in synapses.json |
| Missing inheritance | Add "inheritance": "inheritable" to synapses.json |
| 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 |
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:
Key principle: Iterative validation catches cascading errors before they compound. Each phase builds on previous fixes.
After running the script, Alex should check:
package.json the single source, or are versions hardcoded in prose that will drift?-Mode quick in release checks-Mode llm when updating diagramsScript: .github/muscles/brain-qa.ps1