review-file-size

---
name: review-file-size-35a5d3ba6f07
description: Find files approaching context limits and evaluate whether coupling-aware splits are worthwhile
user-invocable: true
disable-model-invocation: true
---
Enter planning mode. Identify source files approaching the context load limit and evaluate whether they can be meaningfully split. Use parallelism where possible.

## Why This Matters

Files over ~25k tokens cause problems: the Read tool must batch them, they bloat context for tasks that only need a small piece, and they're harder to reason about in a single pass. But splitting a file poorly — into two halves that share all the same globals and must always be loaded together — is worse than one large file. A split only helps if the pieces are **independently useful**.

## Step 1 — Measure file sizes

Scan all `.ahk` files in `src/` and `tests/` (excluding `src/lib/`). For each file, estimate the token count — don't rely on line counts alone. AHK files with long DllCall signatures, inline strings, or dense logic have significantly more tokens per line than sparse files with short functions.

**Approximate token estimation**: Read each file and estimate tokens. Characters ÷ 4 is a rough baseline, but AHK identifiers and camelCase inflate this. Aim for a reasonable estimate, not exact counts.

**Threshold**: Only flag files that are **approaching trouble** — roughly 20k+ tokens. Files well under this threshold are fine regardless of line count. Don't propose splitting a 500-line file that's 12k tokens just because it's "large by line count."

## Step 2 — Analyze internal coupling for flagged files

For each file above the threshold, use the tools to assess whether a split is viable:

| Tool | What It Tells You |
|------|------------------|
| `query_interface.ps1 <file>` | Public functions and globals — are there distinct groups serving different consumers? |
| `query_global_ownership.ps1 <globalName>` | For each global the file uses — who else writes/reads it? Would a split add manifest entries? |
| `query_function_visibility.ps1 <funcName>` | For key functions — who calls them? Would splitting require cross-file calls between the halves? |

**Look for natural seams:**
- Distinct functional sections (init vs runtime vs cleanup, or producer vs consumer)
- Function groups that reference different sets of globals
- Sections that different tasks/skills would load independently

**Look for coupling walls:**
- Most functions reading/writing the same globals (no seam exists)
- Circular call patterns between would-be halves
- A cohesive state machine or event handler where any piece requires the whole

## Step 3 — Evaluate each candidate split

For each file where a seam exists, evaluate the **net benefit**:

**Benefits of splitting:**
- Smaller context loads for tasks that only need one half
- Clearer separation of concerns
- Easier to test pieces in isolation

**Costs of splitting:**
- New ownership manifest entries if globals cross the boundary
- Additional `#Include` dependencies
- Two files that must always be loaded together (if coupling is too tight) = no actual benefit
- Risk of regressions from the refactor itself

**Only recommend a split when the net benefit is clearly positive.** A file at 22k tokens with no natural seam is better left alone than forcibly split into two 11k-token files that are joined at the hip.

## Plan Format

**Section 1 — File size inventory** (only files near/above threshold):

| File | Lines | Est. Tokens | Status |
|------|-------|-------------|--------|
| `gui_state.ahk` | 1400 | ~28k | Above threshold |
| `gui_paint.ahk` | 900 | ~19k | Approaching |
| `viewer.ahk` | 1100 | ~22k | Above threshold |

**Section 2 — Coupling analysis for candidates:**

| File | Natural Seam? | Shared Globals Across Seam | New Manifest Entries | Independently Useful? |
|------|--------------|---------------------------|--------------------|--------------------|
| `gui_state.ahk` | Yes — interceptor vs state transitions | 2 (`gGUI_State`, `gGUI_Sel`) | 0 (both already shared) | Yes — interceptor logic reads different than state logic |
| `viewer.ahk` | Weak — most functions share `gViewer_*` | 8 | 4 new entries | No — halves always loaded together |

**Section 3 — Recommended splits** (only where net-positive):

| File | Split Into | Seam | Tokens Each | Coupling Cost | Benefit |
|------|-----------|------|-------------|--------------|---------|
| `gui_state.ahk` | `gui_state.ahk` + `gui_interceptor.ahk` | Interceptor event handling vs state transitions | ~14k / ~14k | 0 new manifest entries | Tasks investigating input vs state can load one half |

**Section 4 — Files left alone** (above threshold but not worth splitting):

| File | Est. Tokens | Why Not Split |
|------|-------------|--------------|
| `viewer.ahk` | ~22k | All functions share 8+ `gViewer_*` globals — no seam |

Ignore any existing plans — create a fresh one.