cwilliams5/review-constants-to-configs

Enter planning mode. Inventory all hardcoded constants and evaluate which should be promoted to the config registry. Use parallelism where possible.

Tools

| Command | Purpose | |---------|---------| | query_config.ps1 | Browse config registry — sections, groups, existing entries | | query_config.ps1 -Usage <key> | Which files consume a config value |

Step 1 — Inventory constants NOT in the config registry

Scan all src/ files (excluding src/lib/) for hardcoded constants:

• Named constants at file scope (e.g., TIMEOUT_MS := 5000)
• Magic numbers in function bodies that control behavior (timeouts, thresholds, sizes, intervals)
• Hardcoded pixel values, colors, dimensions
• Timer intervals passed to SetTimer
• Sleep durations that control timing behavior
• Buffer sizes, retry counts, polling intervals

Cross-reference each against query_config.ps1 to confirm it's not already in the registry.

Exclude from inventory:

• Windows API constants (WM_ messages, GDI flags, DllCall numeric args) — these are protocol, not tunables
• Array indices, loop bounds tied to data structure size
• Boolean flags (true/false)
• Values in src/lib/ (third-party)
• Constants that are already config-driven via cfg.*

Step 2 — Evaluate which should become config entries

Not every constant belongs in config. The bar is: would an end user reasonably want to change this?

Promote to config when:

• The value controls user-visible behavior (timing, appearance, thresholds)
• Different users/environments may need different values (e.g., slow machines need longer timeouts)
• The value was already asked about in issues or feedback
• Changing it requires editing source code today

Keep as hardcoded constant when:

• It's an implementation detail users shouldn't need to think about (internal buffer sizes, protocol constants)
• Changing it would likely break things (carefully tuned race condition windows, critical section timeouts)
• It's tightly coupled to other values that would also need to change (better to keep them together in code)
• It only makes sense in the context of the surrounding code (not meaningful as a standalone setting)

Keep as hardcoded but name it when:

• It's a magic number in a function body that should be a named constant for readability, but doesn't need to be user-configurable

Config Registry Requirements

For any constant promoted to config, specify:

• Section and Group — where it fits in the existing registry organization
• Key name — following existing naming conventions (check query_config.ps1 for patterns)
• Type — int, float, bool, string, color
• Default — the current hardcoded value
• Min/max — reasonable bounds to prevent broken configs
• Description — one-line explanation for the config editor

Use query_config.ps1 to understand the existing section/group structure before proposing new entries. New entries should fit naturally into existing sections where possible.

Plan Format

Section 1 — Full inventory (all constants found, categorized):

| File | Lines | Constant | Current Value | Category | |------|-------|----------|--------------|----------| | gui_paint.ahk | 42 | BORDER_WIDTH | 2 | Appearance | | gui_state.ahk | 15 | GRACE_PERIOD_MS | 150 | Timing |

Section 2 — Recommended promotions (constants → config entries):

| Constant | File | Value | Config Key | Section | Type | Min/Max | Why Configurable | |----------|------|-------|-----------|---------|------|---------|-----------------| | GRACE_PERIOD_MS | gui_state.ahk:15 | 150 | GracePeriodMs | [Behavior] | int | 50/500 | Users report quick Alt-Tab too sensitive |

Section 3 — Recommended naming only (magic number → named constant, not config):

| File | Lines | Current | Proposed Name | Why Not Config | |------|-------|---------|--------------|---------------| | foo.ahk | 88 | Sleep(50) | POLL_INTERVAL_MS := 50 | Internal polling detail |

Order promotions by user impact: settings users are likely to want first.

Ignore any existing plans — create a fresh one.