# Nexus Module Review

Analyzes a nexus-ui module page (screenshot or module name) and suggests improvements to EntityDefinition, fields, actions, and display modes based on backend metadata.

## Arguments

$ARGUMENTS — Module to review. Accepts:
- A **screenshot** (user pastes image or provides path) — vision identifies the module
- A **module name** (e.g. "contacts", "inventory") — skips screenshot analysis
- Empty — ask the user for a screenshot or module name

## Context detection

Detect execution context by inspecting the working directory:

| Check | Context | Metadata source |
|-------|---------|-----------------|
| `packages/backend/package.json` with `@gzl10/nexus-backend` | **Monorepo** | Read EntityDefinition from source files |
| `package.json` has `@gzl10/nexus-backend` dep | **Project** | Read EntityDefinition from source files |
| Neither | **Remote** | Fetch manifest from API (`GET /api/v1/system/manifest`) |

For **Remote** mode, ask the user for the backend URL if not provided.

## Step 1: Identify module

### From screenshot

Read the image with the Read tool. Extract:
- **Module name**: from header, sidebar highlight, or breadcrumb
- **Active entity tab**: which entity is currently displayed
- **Display mode**: table, board, list, masonry, tree, calendar, timeline
- **Visible columns/fields**: field names from table headers or card content
- **Visible actions**: buttons in toolbar, row dropdown items
- **Data state**: how many rows visible, empty columns, patterns in data
- **UI issues**: anything visually off (truncation, overflow, empty space, alignment)

### From module name

If the user provides a name directly, skip vision and go to Step 2.

## Step 2: Load entity metadata

### Monorepo / Project mode (preferred)

1. Find the module definition:
   ```
   Grep for: export const {moduleName}Module | name: '{moduleName}'
   In: packages/backend/src/modules/ OR src/modules/ OR demos/*/src/modules/
   Also check: plugins/*/src/index.ts (for plugin entities)
   ```

2. Read the module's `index.ts` — extract:
   - All `EntityDefinition` objects (definitions array)
   - All `ActionDefinition` objects (actions array + entity.actions)
   - Module manifest metadata (label, icon, category)

3. For each entity, catalog:
   - **Fields**: name, input type, `db.type`, `meta.showInDisplay`, `meta.showInForm`, `meta.searchable`, `meta.sortable`
   - **Display config**: `displayMode`, `availableDisplayModes`, `groupBy`, `groupableFields`, `calendarFrom/To`, `defaultSort`
   - **CRUD flags**: `allowCreate`, `allowEdit`, `allowDelete`, `hidden`
   - **Features**: `taggeable`, `attachable`, `realtime`, `refreshInterval`
   - **Actions**: scope (module/entity/row), label, variant, disabled condition, batch
   - **CASL**: subject, sensitiveFields, permissions wildcards

### Remote mode (fallback)

Fetch `GET {baseUrl}/api/v1/system/manifest` (no auth needed for public capabilities, but manifest needs auth).

If auth needed:
```bash
nexus client login --url {baseUrl}
nexus client fetch GET /api/v1/system/manifest
```

Parse the ManifestDTO — it contains the same metadata serialized via `toEntityDefinitionDTO`.

## Step 3: Analyze and generate findings

Cross-reference the visible UI (from screenshot) with entity metadata. If no screenshot, analyze metadata standalone for common issues.

### Analysis categories

Run through each category. Only report genuine findings, not noise.

#### 3.1 Display mode fitness

| Check | Finding |
|-------|---------|
| Entity has select/enum fields but no BoardDisplay available | Suggest adding to `availableDisplayModes` + `groupableFields` |
| Entity has date/datetime fields but no CalendarDisplay | Suggest `calendarFrom`/`calendarTo` config |
| Entity has `created_at` + temporal data but no TimelineDisplay | Suggest as available mode |
| Entity type is tree/dag but default display is table | Suggest tree as default |
| `availableDisplayModes` is restricted but useful modes are excluded | Suggest expanding |

#### 3.2 Field visibility

| Check | Finding |
|-------|---------|
| Field with `showInDisplay: true` (or default) but provides little value in tables (e.g., long text, JSON, description) | Suggest `showInDisplay: false` |
| Field important for identification not shown in display (e.g., email, status, type) | Suggest `showInDisplay: true` |
| Too many columns visible (>8 in table) — information overload | Suggest hiding less important ones |
| Too few columns visible (<3) — table feels empty | Suggest showing more relevant fields |
| `labelField` not set or points to a non-descriptive field | Suggest better `labelField` |
| Password/secret field without `sensitiveFields` in CASL | Flag security issue |

#### 3.3 Search and sort

| Check | Finding |
|-------|---------|
| No `defaultSort` configured | Suggest by most recent (if timestamps) or alphabetical (if labelField) |
| Fields that should be searchable but `searchable: false` | Suggest enabling |
| Fields that should be sortable but `sortable: false` | Suggest enabling |
| No fields marked as `searchable` | Suggest at least labelField + key identifier fields |

#### 3.4 Actions review

| Check | Finding |
|-------|---------|
| Row action that doesn't need the row ID (e.g., "Export all") | Suggest entity or module scope instead |
| Entity/module action that logically operates on a single record | Suggest row scope |
| Action without clear label or with generic label ("Execute", "Run") | Suggest descriptive label |
| Batch-capable action not marked `batch: true` | Suggest enabling batch |
| Destructive action without `variant: 'danger'` | Suggest adding danger variant |
| Action with `ConfirmConfig` but confirm message is generic | Suggest specific message |
| Many row actions (>4) — dropdown gets long | Suggest grouping or hiding less-used ones |

#### 3.5 Entity configuration

| Check | Finding |
|-------|---------|
| Collection without `timestamps: true` | Suggest adding (audit trail) |
| Entity with delete but no `softDelete` for important data | Suggest soft delete |
| Entity with `realtime: false` that would benefit from live updates | Suggest `'sync'` or `'live'` |
| Entity suitable for tags but `taggeable` not set | Suggest enabling |
| Entity with file references but `attachable` not set | Suggest enabling |
| `expose: true` (default) for internal/auxiliary entities | Suggest `expose: false` or `hidden: true` |
| Entity with only 1-2 records that should be `single` type | Suggest type change |

#### 3.6 Screenshot-specific (only when screenshot provided)

| Check | Finding |
|-------|---------|
| Empty columns visible in >70% of rows | Suggest `showInDisplay: false` or rethink field |
| Data truncated in columns (ellipsis visible) | Suggest wider column or `showInDisplay: false` |
| Actions visible that don't make sense in current context | Investigate scope mismatch |
| Missing pagination or infinite scroll with many rows | Check pagination config |
| No search bar visible for a collection with many records | Check toolbar rendering |
| Inconsistent date formats | Check field input type |

## Step 4: Present findings

Group findings by priority and category:

```markdown
## Module Review: {moduleName}

### Entity: {entityName} ({type})

#### High impact
- [display] {finding with specific suggestion and code change}
- [fields] {finding}

#### Medium impact
- [actions] {finding}
- [search] {finding}

#### Low impact / Nice-to-have
- [config] {finding}

### Suggested changes

For each high/medium finding, show the specific code change:

**{entity}.fields.{field}:**
```typescript
// Current (inferred)
meta: { showInDisplay: true }
// Suggested
meta: { showInDisplay: false }  // Long text, rarely useful in table view
```
```

## Step 5: Apply changes (optional)

After presenting findings, ask:

```
{N} findings found. Options:
  [1] Apply high-impact changes (I'll edit the EntityDefinition files)
  [2] Create work items in Plane for manual review
  [3] Just the report, thanks
```

- **Option 1**: Edit the source files directly. Only for monorepo/project mode.
- **Option 2**: Create work items using Plane tools (like neural-review).
- **Option 3**: Done.

For option 2, create a single work item with all findings:

```
mcp__neural__plane_work_item_create(
  workspace_slug, project_id,
  name: "review: {moduleName} module UI/DX improvements",
  description_html: "{findings as HTML list}",
  priority: "medium"
)
```

Assign to the relevant module in Plane (`plane_module_add_work_items`).

## Rules

- **Do NOT change entity types** (collection to single, etc.) without explicit user approval
- **Do NOT remove fields** — only suggest visibility changes
- **Do NOT modify CASL permissions** — only flag security issues
- **Do NOT touch migrations** — only EntityDefinition metadata
- **Be specific**: every finding must include the exact field/action/config and the suggested change
- **No false positives**: if unsure, skip. Quality over quantity
- **Context matters**: a CRM module has different needs than an audit log. Adapt heuristics
- **Multiple screenshots**: if the user provides more screenshots of the same module (different tabs, scroll positions), accumulate findings across all of them