# Brain QA

> Brain QA

- Skill: `fabioc-aloha/brain-qa` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add fabioc-aloha/brain-qa`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fabioc-aloha/brain-qa/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: fabioc-aloha (https://skillmd.com/u/fabioc-aloha)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fabioc-aloha/brain-qa

---


# 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

```bash
# 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

```markdown
## 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`_