mastermind-frontend-audit

name	mastermind-frontend-audit
description	Read-only review of a finished UI change against the codegraph — a component nothing renders, a props contract changed without its callers, a reinvented component, or a raw value where the design system has a token. Use after implementing React or Vue work; triggers "review this UI change", "check the component", or a finished frontend diff.
metadata	{"version":"0.1.0","authors":["mastermind"],"tags":["code-review","frontend","components","mmcg"]}

Mastermind frontend audit

A UI change can be structurally wrong while looking fine, and structurally fine while looking wrong. This review covers only the first kind, because only the first kind can be checked against evidence.

You are read-only. You report findings and change nothing.

Collect the delta first

git diff --name-status <baseline>
git diff <baseline> -- <changed component files>

Then ground each changed component in the graph. Never assert a structural fact from reading the diff alone — the diff shows what the change did, the graph shows what the rest of the codebase expects.

The four checks

1. A component nothing renders

For every component the change added, mmcg_callers <Name> gives the components that render it. Zero callers on a brand-new component means it was never wired in — the most common way a UI change passes review and ships as nothing.

Do not report this as dead code. Check the paths the graph cannot see first: a route table, a lazy import(), a story or test file, an export from a barrel consumed outside the indexed tree, or a Vue component auto-imported by build tooling. If one of those explains it, the finding is could_not_verify, not a defect.

2. A props contract changed without its callers

mmcg_symbols_changed_since <baseline> reports signature_changed for a component whose parameters moved. A component's signature carries its props, so this is a public-contract change. Cross it with mmcg_callers: every caller not touched by the diff is a consumer left on the old contract.

A removed or newly-required prop breaks them. An added optional prop does not. Say which, and name the callers — a count is not evidence.

3. A reinvented component

For every component the change added, search the name and its neighbours (Button → BaseButton, AppButton, UiButton) and check mmcg_centrality --prefix <component dir> for what the codebase already leans on. A new component that duplicates the role of an existing one is a finding even when the code is correct, because the duplicate is what future changes will diverge from.

The bar is a named existing component with the same role — not a suspicion that something similar might exist. If you cannot name it, there is no finding.

4. A raw value where the system has a token

Scan the added lines for hex colours, rgb(...), raw pixel spacing, magic z-index, and inline font stacks. Then confirm a token actually exists for that value — a variable, theme key, or design-system constant. A raw value with no token to replace it is not a finding; a raw value that shadows an existing token is.

Evidence rule

A finding names the file, the line, and the query result that establishes it. "Card has no callers" is a claim; "mmcg_callers Card → 0, and Card appears in no route table or story file" is a finding. Without the query, downgrade it to could_not_verify or drop it.

Restraint

Finding nothing is a normal outcome. A change that reuses existing components, leaves contracts intact, and uses tokens is a clean result, and reporting it as clean is the correct output.

Do not pad the report to look thorough. A reviewer that always finds four things is a reviewer nobody reads.

What this review cannot judge

Visual fidelity, spacing, responsive behaviour, and interaction quality are not structural facts and are not in scope. They need the running application, and a clean verdict here says nothing about them. Do not imply the change matches a design.

Output

## Frontend audit: <clean | findings>

### Unrendered components
- `<file>:<line>` — `<Component>` — `mmcg_callers` → 0; checked: <routes, stories, lazy imports, barrels>

### Contract changes
- `<Component>` — `<old signature>` → `<new signature>` — callers left on the old contract: `<file>`, `<file>`

### Duplicates
- `<file>:<line>` — `<New>` duplicates `<Existing>` at `<file>` — <the role they share>

### Raw values
- `<file>:<line>` — `<value>` — existing token: `<token>`

### Kept
- <what the change reused or preserved that was worth reusing>

### Could not verify
- <claim> — <which query was inconclusive and why>

<!-- mastermind:frontend-audit-begin -->
```yaml
baseline: <ref>
verdict: clean | findings
components_added: <N>
components_changed: <N>
flagged: <N>
findings:
  - file: <path>
    symbol: <name>
    kind: unrendered | contract_change | duplicate | raw_value | could_not_verify
```
<!-- mastermind:frontend-audit-end -->

flagged counts every findings entry. verdict is findings when flagged is above zero and clean otherwise. Keep every heading even when empty, and never omit the sentinel block.

Boundaries

• Read-only. Never edit source, reports, audit.md, _lessons.md, or state.json; never stage, commit, or revert.
• Report findings; do not apply them.
• This is not a contract audit. It produces no held / drift / broken verdict and does not replace the controller's post-flight.