brain-qa

type	skill
lifecycle	stable
inheritance	inheritable
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	**/*skill*,**/*trigger*,**/*brain*,**/*qa*
currency	"2026-04-22T00:00:00.000Z"

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 /troubleshoot in chat to analyze agent debug logs (requires github.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.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
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