cwilliams5/review-memory

Enter planning mode. Audit the project's persistent AI context files for factual accuracy against the current codebase. The goal is to find landmines — stale knowledge that would actively mislead a future session.

Philosophy

These files are terse by design. Every line costs context tokens every session. Brevity was hard-won. This skill does NOT:

• Suggest adding new rules or expanding existing ones
• Recommend rewording for "clarity" (clarity costs tokens)
• Question whether a rule is needed — the human knows the history of why each rule exists
• Suggest new patterns, conventions, or best practices

This skill ONLY checks: is what's written here still true?

Scope

• CLAUDE.md — main project instructions
• .claude/rules/*.md — domain-specific knowledge files
• The table in CLAUDE.md that indexes the rules files

Phase 1 — Identifier Verification (Mechanical, High Confidence)

For every concrete identifier referenced in these files, verify it exists in the current codebase.

What to verify

• File paths — src/gui/gui_data.ahk, src/shared/config_registry.ahk, etc. Do they exist at those paths?
• Function names — WL_UpsertWindow(), Blacklist_IsWindowEligible(), _WS_GetOpt(), etc. Do they exist? Use query_function_visibility.ps1.
• Global variable names — gGUI_DisplayItems, StorePipeName, etc. Do they exist? Use query_global_ownership.ps1.
• Config keys — any setting name referenced. Does it exist in the config registry? Use query_config.ps1.
• Tool/script names — check_globals.ps1, query_global_ownership.ps1, shader_bundle.ps1, etc. Do they exist at the referenced location?
• Check names — specific check names referenced (e.g., check_critical_leaks). Do they exist as standalone scripts or sub-checks in batch bundles?
• Command-line flags — --gui-only, --pump, --config, etc. Are they still handled in the entry point?
• IPC message types — any IPC_MSG_* referenced. Do they exist?

Classification

• Broken — identifier doesn't exist. An AI following this instruction will be confused.
• Renamed — old name gone, similar new name exists. Needs updating.
• Moved — exists but at a different path than documented.
• Current — verified correct. No action.

Phase 2 — Architecture Claim Verification (Medium Confidence)

The rules files make factual claims about how the system works. Verify the significant ones against actual code.

What to verify

• Process model — does the process model described in architecture.md match alt_tabby.ahk's mode routing? Are all modes listed? Any new ones missing?
• Key files table — does the "Key Files" section list files that exist with accurate descriptions of what they contain?
• Producer list — are all producers listed? Any new ones not mentioned?
• State machine — does the state diagram match the actual states in the code?
• Compositor stack — does the layer ordering match gui_effects.ahk / gui_paint.ahk?
• Config system description — does it match how config_registry.ahk actually works? Are the registry entry fields (s, k, g, t, default, d, min, max, fmt) still accurate?
• IPC architecture — does the described pipe protocol match the actual implementation?
• Keyboard hook defense stack — are all the defense layers listed in keyboard-hooks.md still present in the code?

Don't verify every claim — focus on structural claims that, if wrong, would lead an AI to make incorrect architectural decisions.

Classification

• Contradicts code — the code does Y, the rule says X. One of them changed and the other didn't keep up.
• Incomplete — a list or description is missing entries that now exist (e.g., new producer, new state, new compositor layer). The existing entries are correct.
• Current — verified correct.

Phase 3 — Redundancy with Static Analysis (High Value)

Rules that are now mechanically enforced by static analysis checks are the best candidates for removal — the check does the job better and costs zero context.

For each rule in CLAUDE.md and the rules files that describes a coding pattern to follow or avoid:

1. Check if a corresponding check_*.ps1 (or sub-check in a batch bundle) enforces this mechanically
2. If yes, flag it as Redundant — enforced by [check name]

The rule should still exist if it explains why (the AI needs to understand the principle to write correct code). But if the rule is purely "do X, don't do Y" with no judgment component, and a check enforces it, the rule can likely go.

Examples of what this catches:

• "Always declare globals inside functions" — if check_globals in check_batch_functions.ps1 catches this, the rule is redundant as enforcement (though the explanation of AHK v2 scoping may still be needed)
• "Don't call _Private() functions cross-file" — if query_function_visibility.ps1 -Check enforces this, the rule is redundant

Phase 4 — Rules Index Table

CLAUDE.md has a table mapping .claude/rules/ files to their contents:

| File | Contents |
|------|----------|
| `ahk-patterns.md` | AHK v2 syntax, race conditions, ... |

Verify:

• Every file listed in the table exists
• Every .md file in .claude/rules/ is listed in the table
• The one-line descriptions roughly match actual file content (don't nitpick — just catch "file was completely rewritten but description is from the old version")

Phase 5 — File Size Check

Report the line count of each file:

| File | Lines | |------|-------| | CLAUDE.md | N | | .claude/rules/ahk-patterns.md | N | | ... | ... |

No threshold — just surface the numbers so the human can spot gradual bloat. Flag any file over 150 lines as worth a glance, since these load every session.

Explore Strategy

Run in parallel by file — each rules file is independent:

• Agent 1: CLAUDE.md (identifiers, architecture claims, rules index table)
• Agent 2: ahk-patterns.md + keyboard-hooks.md (identifiers, patterns vs checks)
• Agent 3: architecture.md + komorebi.md (architecture claims, producer list, state machine)
• Agent 4: testing.md + debugging.md + workflow.md + installation.md (identifiers, tool references)

After agents report, do Phase 3 (redundancy check) yourself — it requires cross-referencing rules against check scripts.

Output Format

Mechanical Issues

Objectively wrong — identifiers, paths, names.

| File | Reference | Type | Status | Details | |------|-----------|------|--------|---------| | architecture.md | src/gui/gui_store.ahk | File path | Renamed | Now src/gui/gui_data.ahk | | CLAUDE.md | _WS_GetOpt() | Function | Broken | Function no longer exists | | ahk-patterns.md | check_globals.ps1 | Script | Moved | Now a sub-check in check_batch_functions.ps1 |

Architecture Drift

Claims that contradict or lag behind the current code.

| File | Claim | Reality | Impact | |------|-------|---------|--------| | architecture.md | Compositor has 7 layers | Code shows 9 layers | AI will miss layers when reasoning about paint order | | architecture.md | "EnrichmentPump" section missing stats flush | Stats flush now runs in pump | AI may put stats work in MainProcess |

Redundancy Candidates

Rules now enforced by static analysis. Human decides whether the explanation is still worth the context cost.

| File | Rule | Enforced by | Recommendation | |------|------|-------------|----------------| | CLAUDE.md | Global declaration requirement | check_globals in check_batch_functions.ps1 | Keep explanation of why, remove the "must do" directive | | ahk-patterns.md | No cross-file _Func() calls | query_function_visibility.ps1 -Check | Rule is pure enforcement — check handles it |

File Sizes

| File | Lines | Note | |------|-------|------| | CLAUDE.md | N | | | .claude/rules/ahk-patterns.md | N | | | ... | ... | |

Index Table Discrepancies

Any mismatch between the rules index in CLAUDE.md and the actual .claude/rules/ directory.

Order all tables by impact: broken references that cause wrong decisions first, cosmetic issues last.

Ignore any existing plans — create a fresh one.