---
name: ui-eng-vision-orchestrator
description: High-level orchestrator for managing multi-pass migration of Chrome DevTools legacy components to the modern UI engineering vision (UI.Widget & Lit-html).
allowed-tools: code_search open_urls search_changelists data_analysis import_skill close_skill
---

# UI Engineering Vision Orchestrator: Meta-Skill Instructions

This meta-skill acts as the central coordinator for modernizing legacy Chrome
DevTools views into declarative `UI.Widget` components based on lit-html,
managing a multi-pass sequential CL pipeline to ensure each code modification is
small, testable, and highly reviewable.

Refer to [ui_engineering.md](../../../docs/ui_engineering.md) for general
principles.

--------------------------------------------------------------------------------

## 1. Migration Philosophy & Plan-Validate-Execute Pattern

1.  **The Plan-Validate-Execute Principle**: For each target file, the
    orchestrator must first generate a structured `migration_plan.md` listing
    the exact transformations, file targets, and subskills allocated for each
    pass.
2.  **User Acceptance Gate**: The orchestrator must halt execution and present
    the migration plan to the user. No code modification, subskill loading, or
    CL staging can occur until the user explicitly accepts the plan.
3.  **No Assumptions on Inheritance**: Do not assume the class hierarchy in a
    file matches older patterns or generic examples. Always perform a structure
    analysis of the active file first and adapt the plan to the actual, current
    code.
4.  **Hybrid Files/Multiple Classes**: Files may contain multiple classes in
    different states of modernization (e.g., one partially migrated class and
    one fully legacy class). If the file being migrated contains several
    classes, the migration needs to be done separately for each class, starting
    with the leaves and going up the dependency chain. Propose modifications
    only for classes with actual violations.
5.  **Coupling Analysis**: Always check the integration files (e.g., sidebar
    files, parent panel files) where the target class is instantiated to see if
    there are any direct `.element` or `.contentElement` couplings. If found,
    include the decoupling of these references in the plan.
6.  **Neighboring Component Reference**: Inspect neighboring modernized files of
    the same archetype (e.g., `DOMStorageItemsView.ts` or
    `KeyValueStorageItemsView.ts` for storage-like components) to find proven
    patterns for toolbar and data-grid configurations.
7.  **The Narrow Bridge Principle**: Keep code modifications tightly scoped to a
    single responsibility per CL. Do not combine technology migrations (e.g.,
    converting imperative DOM to Lit-html) with base class refactoring in the
    same diff.
8.  **Strict Intermediate Stability**: The code must compile and work correctly,
    and all tests must pass after each step. We should not split the class API
    update from its usage update.
9.  **Establish Comprehensive Guardrails First**: Ensure both **logic tests**
    (verifying presenter interactions and state updates) and **screenshot
    tests** (verifying layout/styling) exist before rewriting code. If coverage
    is missing, scaffold it first.
10. **Pre-flight Clarification**: Before starting, verify if the task is
    underspecified or ambiguous. If so, point this out and ask for
    clarifications before proceeding.
11. **Step Sizing & Complexity Assessment**: Assess the complexity of each step
    beforehand. Aim for intermediate steps that involve changing or adding
    roughly 300 lines of code. If a step is predicted to be too complex, break
    it down into smaller substeps. The agent must stop and report back after
    each step or substep to allow verification.

--------------------------------------------------------------------------------

## 2. Multi-Pass Execution Lifecycle

### Plan Generation (Gated)

*   **Actions**:
    1.  Verify if the task is underspecified or ambiguous. If so, ask for
        clarifications first.
    2.  Scan the target file to determine size, complexity, legacy elements
        (e.g., `ReportView`, `ToolbarButton`, `DataGrid`, `TreeOutline`), and
        actual class inheritance. Deconstruct the file mentally (or in the plan)
        into **Business Logic** (state, event handlers) and **Rendering Logic**
        (DOM creation, CSS classes). Reference code elements by **Name** (not
        line numbers) to ensure the plan remains valid as the codebase evolves.
        Check if the class dependencies have been migrated to the ui eng vision
        or not. If the file contains multiple classes, plan the migration
        separately for each class, starting with the leaves and going up the
        dependency chain.
    3.  Check the files depending on this file, to understand how the code in
        this file is being used.
    4.  **Dynamic Ordering Decision**: Determine whether to run Logic
        Consolidation first or Local lit-html rendering first:
        *   **Option A (Logic First)**: Choose this if the component has a
            complex, nested state model or highly coupled event-handlers.
            Consolidating the state variables and defining the `ViewInput`
            interface first provides a clean data contract, making the
            subsequent template conversion highly deterministic.
        *   **Option B (Technology First)**: Choose this if the component has a
            relatively simple state flow but massive, deeply nested imperative
            DOM construction. Converting the layout to declarative Lit templates
            first (using temporary inline or local state) makes it much easier
            to isolate and group the remaining state updates afterward.
    5.  Generate a `migration_plan.md` reflecting this ordering and outlining
        the target steps.
    6.  Halt execution and print the formatted plan in Markdown to the chat.
        Wait for user approval.

### Baseline & Safety Scaffolding

*   **Trigger Condition**: User explicitly says "I accept the plan" or
    equivalent.
*   **Subskill to Import**: `ui-eng-vision-test-scaffolder`
*   **Actions**:
    1.  Verify existing test coverage. Propose and add missing **logic tests**
        for interactions and **screenshot tests** for visual validation to avoid
        regressions.
    2.  Pay extra attention not to skip this step.

### Logic Consolidation

*   **Trigger Condition**: Baseline tests green (or respective previous pass
    staged).
*   **Subskill to Import**: `ui-eng-vision-logic-consolidator`
*   **Actions**:
    1.  Extract manual elements, constructor DOM configurations, and imperative
        updates into private update helper methods with structured
        state-passing.

### Local Lit-HTML Rendering (Technology Migration)

*   **Trigger Condition**: Previous pass staged.
*   **Subskill to Import**: `ui-eng-vision-local-lit-renderer`
*   **Actions**:
    1.  Migrate imperative elements to declarative templates (using component
        mapping rules defined inside the subskill) and render them locally
        within the existing view.

### Widget Promotion (Architectural Bridge)

*   **Trigger Condition**: Both local template rendering and logic consolidation
    staged.
*   **Subskill to Import**: `ui-eng-vision-widget-promoter`
*   **Actions**:
    1.  Promote view classes to modern `UI.Widget` classes, hook up
        `performUpdate()` delegates, export the default view layout, and clean
        up legacy wrappers.
