Menu
>-
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
| 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" |
Semantic, logic, code, and architectural validation of Alex's cognitive architecture — not just file counts, but meaning coherence
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.
# Generate brain health grid
node .github/muscles/brain-qa.cjs
The output is written to .github/quality/brain-health-grid.md.
/troubleshoot in chat to analyze agent debug logs (requires github.copilot.chat.agentDebugLog.enabled)| 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 | 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 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 |
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.
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.
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 diagramsDream runs the scans. This skill teaches how to read and act on the results.
| 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% |
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 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 |
## 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 | ✅/⚠️/🔴 |
Script: .github/muscles/brain-qa.cjs
End-to-end academic paper drafting for CHI, HBR, journals, and conferences with venue-specific templates, drafting workflows, and revision strategies.
Detect, create, and manage the AI-Memory fleet communication channel. Fires on bootstrap, session start (announcements), and feedback writes.
Generate on-brand Alex — ACT Edition SVG banners for documents (READMEs, plans, notes, release artifacts)
Patterns for fiction, narrative structure, character development, dialogue, and storytelling craft.
Challenge what you think is right — alternative hypotheses, missing data, evidence quality, bias detection, falsifiability, and adversarial review
Convert Word documents (.docx) to clean Markdown with image extraction and pandoc cleanup