Architecture audit

Architecture Audit

Comprehensive project consistency review across code, documentation, diagrams, and configuration

Overview

Systematic audit process to ensure all project artifacts stay synchronized. Catches version drift, terminology inconsistencies, outdated diagrams, broken references, and code-to-docs mismatches.

⚠️ IMPORTANT: This skill audits the user's project code, NOT the the AI assistant cognitive architecture in .github/. Ignore .github/ folder contents when performing audits - focus on the actual source code, documentation, and configuration in the project root and subdirectories.

Triggers

• "audit", "comprehensive review", "fact-check"
• "consistency check", "project health"
• "pre-release audit", "documentation review"
• Before major releases or after significant refactoring

Audit Checklist

1. Version Consistency

# Find version references in common locations
# EXCLUDE: .github/** (the AI assistant cognitive architecture - not project code)
$patterns = @(
    'package.json',           # "version": "x.y.z"
    'src/**/config*.json',    # Version in config files (not .github)
    '*.md',                   # Root documentation only
    'docs/**/*.md',           # Project docs (not .github)
    'src/**/constants.ts',    # Hardcoded versions
    'CHANGELOG.md'            # Version headers
)

# Grep for version patterns
Get-ChildItem -Recurse -Include $patterns |
    Select-String -Pattern 'v?\d+\.\d+\.\d+' |
    Group-Object -Property Line

Check: All version references match the canonical version (usually package.json)

2. Terminology Consistency

Build a deprecated terms list for your project:

Deprecated Term	Current Term	Migration Pattern
DK-*.md	skills/*/SKILL.md	File format change
domain-knowledge/	skills/	Folder rename
(project-specific)	(project-specific)	(document here)

# Search for deprecated terms (exclude .github/)
$deprecated = @('OLD_TERM_1', 'OLD_TERM_2')
foreach ($term in $deprecated) {
    Get-ChildItem -Recurse -Include "*.md","*.ts","*.json" -Exclude ".github" |
        Where-Object { $_.FullName -notmatch '\\.github\\' } |
        Select-String -Pattern $term
}

3. Fact Inventory

Maintain a facts file or section with current counts:

## Current Facts (Update on Audit)
- Skills: 46 folders
- Commands: 16 total
- Tools: 11 MCP tools
- Agents: 5 custom agents
- Instructions: 19 files
- Prompts: 7 files

Check: All documentation referencing these counts matches actual values

4. Diagram Validation

For each diagram (Mermaid/ASCII):

• Node labels match current terminology
• Counts in labels are accurate
• Flow directions reflect actual data flow
• Subgroup names are current
• No references to deprecated concepts

# Find all diagrams in project (exclude .github/)
Get-ChildItem -Recurse -Include "*.md" |
    Where-Object { $_.FullName -notmatch '\\.github\\' } |
    Select-String -Pattern '```mermaid|```ascii|┌|╔' |
    Group-Object -Property Path

5. Cross-Reference Validation

• Internal links resolve ([text](path) → file exists)
• Anchor links work (#section-name → heading exists)
• Image references valid
• Import/require statements resolve

# Find markdown links in project (exclude .github/)
Get-ChildItem -Recurse -Include "*.md" |
    Where-Object { $_.FullName -notmatch '\\.github\\' } |
    Select-String -Pattern '\[.*?\]\((?!http)[^)]+\)' |
    ForEach-Object {
        # Extract path and verify existence
    }

6. Code-to-Docs Sync

Code Artifact	Documentation Location	Check
Exported functions	API docs	Signatures match
Config options	README/User Manual	All options documented
CLI commands	Help text / docs	Commands listed
Error messages	Troubleshooting	Errors explained

7. Configuration Alignment

• TypeScript constants match documentation
• JSON schemas match actual structure
• Environment variables documented
• Feature flags documented

Audit Report Template

# Architecture Audit Report
**Date:** YYYY-MM-DD
**Version Audited:** x.y.z
**Auditor:** [name/AI]

## Summary
| Category | Status | Issues Found |
|----------|--------|--------------|
| Version Consistency | ✅/⚠️/❌ | N |
| Terminology | ✅/⚠️/❌ | N |
| Fact Accuracy | ✅/⚠️/❌ | N |
| Diagrams | ✅/⚠️/❌ | N |
| Cross-References | ✅/⚠️/❌ | N |
| Code-Docs Sync | ✅/⚠️/❌ | N |

## Issues Found
### [Category]
- **File:** path/to/file
- **Line:** N
- **Issue:** Description
- **Fix:** Suggested correction

## Actions Taken
- [ ] Issue 1 fixed
- [ ] Issue 2 fixed

Automation Opportunities

Pre-commit Hook

# .husky/pre-commit or similar
npm run audit:quick  # Fast checks only

CI Pipeline

# GitHub Actions
- name: Architecture Audit
  run: npm run audit:full
  if: github.event_name == 'pull_request'

Scheduled Audit

# Weekly full audit
on:
  schedule:
    - cron: '0 9 * * 1'  # Monday 9am

Anti-Patterns

❌ Skipping audits before release — Drift accumulates silently

❌ Manual-only audits — Automate what you can

❌ Fixing without documenting — Record the pattern for next time

❌ Ignoring "cosmetic" issues — They signal deeper drift

❌ Auditing only changed files — Drift affects unchanged files too

Best Practices

✅ Run full audit before major releases

✅ Add new deprecated terms as you migrate

✅ Update fact inventory after structural changes

✅ Document audit findings for patterns

✅ Automate repetitive checks

✅ Time-box manual review (don't boil the ocean)

Integration with Other Skills

• release-preflight → Trigger audit before release
• brain-qa → Connection validation and architecture health
• code-review → Audit as part of PR review
• refactoring-patterns → Audit after major refactoring

---

your AI assistant Extensions

your AI assistant-specific audit procedures that extend the generic project audit above. These leverage knowledge of exact folder structure, heir relationships, safety imperatives, and build/release workflows.

Audit Philosophy (Semantic + Structural)

Dimension	Script (Automated)	the AI assistant (With This Skill)
Structural	File existence, counts, format	✅ Automated
Semantic	—	Do files describe concepts consistently?
Logic	—	Are documented workflows achievable?
Code	Compile, lint, bundle	Does code match documented claims?
Architectural	Version alignment, heir sync	Is memory architecture reflected accurately?

Master-Only Sections (1-9)

#	Section	What It Checks
1	Version Alignment	package.json ↔ CHANGELOG ↔ copilot-instructions
2	Heir Folder Sync	Master → heir file counts
3	Skill Inheritance	SKILL_EXCLUSIONS in sync-architecture.cjs
4	Safety Imperatives	Kill switch, protection markers
5	Build Artifacts	dist/extension.js exists and recent
6	Documentation Cross-Refs	Required links between docs
7	Connection Health	Valid links, no orphans
8	alex_docs Audit	Version refs, deprecated terms
9	Skill Network Diagram	Node count matches actual skills

Inheritable Sections (10-22)

#	Section	What It Checks
10	Extension UI	Dead buttons
11	Dependency Health	npm audit vulnerabilities
12	TypeScript & Lint	Compile errors, lint warnings
13	Security	Secrets in code, CSP compliance
14	Bundle Size	extension.js size
15	Git Hygiene	Uncommitted changes, branch status
16	Changelog	Format, version alignment
17	API Compatibility	Deprecated VS Code APIs
18	Test Coverage	Test file count vs source files
19	Accessibility	ARIA labels, CSS variables
20	Localization	l10n configuration
21	Asset Integrity	Icon exists, no missing assets
22	Configuration Files	launch.json, tsconfig.json, .vscodeignore

Production Scripts

# Full audit (all 22 sections)
node .github/muscles/brain-qa.cjs

# Quick audit (sections 1-9)
node .github/muscles/brain-qa.cjs --mode quick

# Specific sections
node .github/muscles/brain-qa.cjs --mode quick --quiet

Semantic Review Checklist (Manual — Not Scriptable)

• Cross-heir semantic parity: M365 system prompt matches copilot-instructions
• Deprecated terminology: No "DK files" / "domain-knowledge/" in active files
• Claim vs. reality: README features match package.json commands
• Process logic: Heir evolution, meditation, dream workflows internally consistent
• Architectural model: Memory architecture described consistently everywhere
• Code behavior: TypeScript handlers match instruction file docs
• Version source of truth: package.json is canonical