Control-Archaeology Refactor
A long-lived AI tool accretes modes. Each new feature lands as a toggle, a switch, or an icon-button next to the previous ones. After a few quarters the left panel has five overlapping modes selected by three different control types, with mutual-exclusion enforced by hiding siblings. No user can discover the modes without trial and error. The surface needs an excavation, not another button.
Signs to look for
- A single component over ~3,000 LOC that owns the surface.
- Modes selected via mixed control types (Switch + icon button + carousel + tab) in the same control bar.
- Mutual exclusion by hiding — turning mode A on hides mode B's controls, so the user can't see what they're losing.
- Admin-only toggles take visual space for non-admins.
- Mode discovery requires reading the code or asking an internal user.
If three or more of these are true, the surface needs the refactor.
Mechanism
- List every mode the surface supports. Annotate which are user-visible vs. admin-only vs. dead code.
- Group modes by relationship. Most surfaces have one primary axis (what am I doing?) and zero or more secondary axes (how am I doing it?). The primary axis becomes top-tab navigation; the secondary axes stay in-panel as proper sub-controls under the active tab.
- Promote the primary axis to top-tab navigation. Tabs are mutually exclusive by design, visible at all times, and label themselves. Mode discovery is solved by the tab labels.
- Drop the dead toggles. Provider/prompt-model toggles, admin-only flags, A/B-test switches with a clear winner — all out. The diff is part of the win.
- Reorganize within each tab around the natural flow. If a tab has a step sequence (e.g. persona → voice → video), lay it out as a hero-flow, not as parallel controls.
Why it works
The original control bar tries to be all axes at once. The refactor separates axes by hierarchy: tabs handle the primary choice, panel handles its consequences. Each layer has one job. Users can answer "what mode am I in?" in zero seconds (read the tab) instead of three (audit the toggle states).
Example — an avatar-generation surface
A real refactor: a single component, 7,113 LOC, owned five overlapping modes — collaborative, campaign, separate-vs-mixed control, edit, voice. Each was toggled by a different control type. Provider and prompt-model toggles took visual space for non-admins.
After the excavation:
- Top-tabs: Generate · Campaign · Edit (Appearance) · Voice. The primary axis surfaced.
- Dropped: provider/prompt-model toggles (admin-internal), Separate-vs-Mixed (kept the merged-only mode that had won).
- Reorganized Voice: the audio → video pipeline laid out as a hero-flow instead of parallel toggles.
Same functionality. Half the cognitive load. Mode discovery is now a side effect of looking at the screen.
Pitfalls
- Renaming tabs that look like the old toggles. If the tab labels mirror the old switch labels word-for-word, returning users won't notice the change. Use new names.
- Tab-count creep. Five tabs is already a lot. If you reach seven, the surface is actually two surfaces in a trench coat; split it.
- Stateful tab persistence. Remembering the last active tab per user is usually right; remembering it globally is not. Scope persistence to the entity (this avatar's last tab, not "the avatar tab in general").