fabioc-aloha 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
/troubleshootin chat to analyze agent debug logs (requiresgithub.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 | 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 | assets/ contains expected banner 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 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.
Finding Triage Decision Table (AC1)
When brain-qa produces findings, classify each one before acting:
| Finding Class | Example | Action | Rationale |
|---|---|---|---|
| fm=0 (missing frontmatter) | Skill lacks name or description |
Fix now — add frontmatter | Blocks load-time discovery; zero-cost fix |
| fm=0 (invalid type/lifecycle) | type: unknown |
Fix now — correct to valid enum | Blocks all typed-frontmatter consumers (FM4+) |
| tri=0 (missing trifecta partner) | Skill has no instruction | Track as debt — unless skill is extended tier |
Many extended skills are standalone by design |
| self-contained fail | SKILL.md references file that doesn't exist | Fix now — update path or remove reference | Broken reference = runtime failure |
| sync drift (master ≠ heir) | Instruction differs by 2 lines | Fix now — run sync-to-heir.cjs |
Drift compounds; cheap to fix |
| applyTo missing | Domain instruction has no glob | Fix now — add glob pattern | Without it, loads on every request (token waste) |
| stale currency | Date >365d on stable file | Fix if material — check if content actually changed | Stale date ≠ stale content; verify before re-stamping |
| boilerplate description | "Description of skill" | Fix now — write real description | LLM uses description for routing; boilerplate = invisible skill |
| token budget warning | copilot-instructions.md >300 lines | Review — may be false positive if content is dense | Size threshold is heuristic; check value density |
| no decision table | Skill SKILL.md has <3 table rows | Track as debt — unless skill is pure reference | Not all skills need decision tables (e.g., reference-only skills) |
Priority order: fm=0 > self-contained fail > sync drift > boilerplate > tri=0 > stale currency > token budget.
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.jsonthe 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 quickin release checks - LLM Content Audit: Run
-Mode llmwhen 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