analyze-ui

Files (1)

• SKILL.md

SKILL.md (first lines)

# Existing UI Analysis

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

## Desired Outcome

A complete, source-cited model of the existing UI, and four views of it:

1. **UI inventory** — `ui-inventory.json`: every screen (`UIS-`), component (`UIC-`), feature
   (`UIF-`) and task, in the shape of @rules/ui-analysis.md §3. The canonical model; the views are
   projections of it.
2. **Design tokens** — `ui-design-tokens.json`: the colors, type, spacing, radius, borders and
   shadows the UI uses, as W3C DTCG with provenance and clusters, ready for
   `/product:design-system --import`.
3. **Screen catalog** — per screen, its INPUT (fields, controls, validation and where it runs),
   OUTPUT (displayed data, tables, messages), actions and where they land, access, and the code
   behind it; the transition diagram; the business logic found in the view layer.
4. **Features** — the capabilities the screens expose, the tasks users walk to use them, who uses
   them and what they touch.
5. **Components** — the reusable UI parts, their variants and states, where they are used, and
   where the same element was rebuilt by hand.
6. **Design-system extract** — the as-is visual language, its fragmentation, and the semantic token
   candidates for a consolidated design system.

## Decision Criteria

- **Read the route map before the templates.** Routes decide which templates are screens
  (@rules/ui-analysis.md §1–2). A template reachable by URL is a screen even when nothing links to
  it — that is how an orphan becomes visible; a template that is neither a screen, a component nor
  included anywhere goes to `coverage.unresolved`.
- **Every screen, no sampling.** Three hundred screens yield three hundred entries, extracted in
  batches (§8 of the rule). Coverage is reported, never implied.
- **Record what the code does, not what it should do.** A rule enforced only by a script is
  `where: client`; a role check that exists only in a JSP is a `view` guard; a discount computed in a
  scriptlet is embedded logic. These are findings, and the inventory is where they are first
  visible.
- **Cite everything.** Every input, validation, action, message, guard, image, color pair and token
  carries a `source` into the target code.
- **Use the ui-to-domain vocabulary** — form fields → attributes, user action → a verb-first
  Command, action result → state or event (@rules/product/ui-to-domain.md) — so the as-is inventory
  and any to-be mock can be compared field by field.
- **Keep the fragmentation.** Near-identical values are separate raw tokens grouped by `cluster`;
  merging them here would erase the finding (@rules/ui-analysis.md §5).

## Prerequisites

| Input | Required/Recommended | Source | If missing |
|-------|---------------------|--------|------------|
| target_path (argument) | Required | User, or `target_path` in `work/pipeline-progress.json` | Ask for it; stop if it is not a directory |
| `reports/before/{project}/technology-stack.md`, `codebase-structure.md` | Recommended | `/architect:investigate` (it precedes this phase in a pipeline run) | Detect the UI technology from build files and extensions yourself (Step 2) |
| `reports/before/{project}/ui-inventory.json` | Optional | A previous run of this skill | First run: ids start at 001 |
| `work/traceability.json` | Optional | Any earlier skill | Created as `{ "schema_version": 1, "nodes": [] }` |
| `work/context.md` § Open Questions | Optional | All skills | Created on first entry |

`{project}` is `project_name` in `work/pipeline-progress.json` (fallback: the target directory's
base name) — the directory `/architect:investigate` writes to.

## Invocation

```
/architect:analyze-ui [target_path] [--ui-root=<path>] [--auto]
```

| Argument/Flag | Required | Description |
|---------------|----------|-------------|
| `target_path` | Optional | The codebase to analyze; defaults to `target_path` in `work/pipeline-progress.json` |
| `--ui-root=<path>` | Optional | A UI source root, relative to `target_path` or absolute. Repeatable. Use when the UI lives outside the detected roots (a separate frontend repository, a second web module) |
| `--auto` | Optional | Ask nothing: every unresolved route, target, guard or behaviour question becomes an `unasked` Open Question (@rules/open-questions.md §5). `/architect:pipeline` invokes it this way |

## Available Resources

- **Serena MCP** — activate the target first (`activate_project` with `target_path`), then
  `find_symbol` / `find_referencing_symbols` for handler → service → entity and for where a request
  parameter is validated server-side. Without Serena, Grep and Read do the same on a small codebase.
- **Glob/Grep/Read** — templates, routes, includes, resource bundles, style and script files
- **Agent (general-purpose)** — batched per-screen extraction (Step 4)
- `tools/lib/ui_inventory.py` — validates the inventory (Step 8)
- `tools/lib/ui_metrics.py` — the navigation, task and consistency figures (Step 9)
- `tools/lib/ui_views.py` — renders the four views from the inventory (Step 9)

## Execution

Write each step's output as soon as the step completes. Intermediate results go under
`work/ui-analysis/`, so an interrupted run resumes from the last completed step.

### Step 0: Register the phase

Stamp `analyze-ui` in `work/pipeline-progress.json` as `in_progress` with `"plugin": "architect"`
and `started_at`, per @skills/common/progress-registry.md — before reading anything else.

### Step 1: Resolve the scope

1. Resolve `target_path`, `{project}` and the UI roots (`--ui-root`, else detected in Step 2).
2. Read the investigate reports if they exist — the Presentation Layer section of the technology
   stack names the UI framework and roots.
3. Load the previous inventory, if any, for id stability (@rules/ui-analysis.md §7), and read
   `work/traceability.json` for the highest existing `UIS-` / `UIC-` / `UIF-` numbers.
4. Load the Open Questions store and pick up any `deferred` / `unasked` entry about the UI
   (@rules/open-questions.md §7).

**No UI layer** — no templates, no SPA, no server-rendered views (a pure API or batch system): write
nothing, stamp the phase `skipped` with `summary: "no UI layer found"`, and stop.

### Step 2: Detect the technology

Apply the detection table of @rules/ui-analysis.md §2: build files and dependencies first, then
file extensions. Record each technology with the file that proves it. Identify **vendored**
third-party assets (`js/lib/`, `webjars/`, `node_modules/`, a UI framework's `*.min.css`) and build
output (`build/`, `target/`, `out/`, compiled `*_jsp.java`) so the later steps exclude them. Write `work/ui-analysis/technologies.json`.

### Step 3: Build the route map and the screen list

Read every route source the technology has (`web.xml`, `@WebServlet`, `struts-config.xml`,
`@RequestMapping`, router configuration) and follow each route through its handler: to the template
it renders, and to where its success path redirects or forwards.

- A route that renders a template is a **screen** (@rules/ui-analysis.md §1) — including a landing
  page with nothing to do on it. A template reachable by URL without a route (a JSP outside

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect