# code-review

Adopt this skill: https://proskills.md/skills/other/chromedevtools-devtools-frontend-agents-skills-code-review

Page: https://proskills.md/skills/other/chromedevtools-devtools-frontend-agents-skills-code-review
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/code-review/SKILL.md
size: 13596
sha: f740978692e56dd337169bd8e2ccc466eaaab86b
upstream: https://github.com/chromedevtools/devtools-frontend/blob/main/.agents/skills/code-review/SKILL.md

```text
---
name: code-review
description: Generic checklist for reviewing DevTools CLs (your own before upload, or someone else's on Gerrit). Covers test correctness (tautological/vacuous tests, cleanup, leaks), code clarity, CL hygiene, and points to the specialized skills to consult for imports, UI, testing, strings, models, and verification. Use when asked to review a CL, a diff, a patch, or to self-review before `git cl upload`.
---

# Code Review

This checklist comes from recurring reviewer feedback on landed DevTools CLs.
Use it for self-review before upload and for reviewing other people's CLs.

## 1. Gather context

- **Automated Review Agent (diff already in prompt):** Do not run shell
  commands. Use `read_file` to inspect enclosing classes/functions/tests and
  `search_files` to verify callers or conventions across the repository.
- **Local CLI / Interactive session (no diff in prompt):**
  - **Local change:** `git diff origin/main...HEAD` (or `git show HEAD` for a
    single-commit branch). To learn about the branch and upload workflow, see the
    `devtools-version-control` skill.
  - **Gerrit CL:** strip the leading `)]}'` line from each response to get JSON:
    - Diff: `git cl diff` (for the current branch), or fetch the patch set.
    - Inline comments:
      `curl -s https://chromium-review.googlesource.com/changes/devtools%2Fdevtools-frontend~<CL_NUMBER>/comments | tail -n +2`
    - Messages:
      `.../changes/devtools%2Fdevtools-frontend~<CL_NUMBER>/messages`
  - Read the CL description first. Then check that the diff does what the
    description says, and nothing else.

## 2. Consult the specialized skills and rules

Load the skill or `.agents/rules/` files that match what the diff touches, and apply their rules:

| If the diff touches… | Load skill or rules |
| :--- | :--- |
| Any `import` statement, or a new cross-module dependency | `devtools-imports` |
| `UI.Widget`, lit-html views, components, CSS, or UI layout changes | `ui-widgets`, `visual-regression-audit` |
| Reviewing UI and widgets (`front_end/(panels|ui)/**/*.{ts,css}`) | `.agents/rules/ui-and-widgets/*.md` |
| Migration of legacy imperative DOM to widgets or Lit | `ui-eng-vision-orchestrator` (and its sub-skills) |
| New or changed tests: choosing unit, API, or E2E | `devtools-testing-guidance` |
| Reviewing tests (`*.test.ts`, `test/**`, `front_end/testing/**`) | `.agents/rules/tests/*.md` |
| Tests that use `describeWithEnvironment` or `describeWithMockConnection`, or foundation modules | `foundation-test-migration` |
| Ported Chromium web tests (`web_tests/http/tests/devtools`) | `migrate-chromium-test` |
| Flaky or disabled tests, or `it.skip` / `it.skipOnPlatforms` | `fix-tests` |
| Rendering user-controlled strings (URLs, names, console text) | `devtools-unicode-escaping` |
| Adding or modifying `UIStrings` or `@description` / `@example` L10n comments | `devtools-uistrings` |
| `front_end/models/*`, `BUILD.gn`, `devtools_grd_files.gni`, entrypoints | `devtools-model-management` |
| Reviewing foundation, models, and build configs (`front_end/(core|models|entrypoints|generated)/**`, `BUILD.gn`, `*.gni`) | `.agents/rules/models-and-core/*.md` |
| Merging modules or consolidating `BUILD.gn` | `merging-devtools-module` |
| `Settings` registrations and descriptors | `devtools-setting-migration` |
| Stack traces, source maps, `DebuggerWorkspaceBinding` | `devtools-source-maps` |
| Building, running tests, or lint | `devtools-verification` |

## 3. Boundaries vs. Interiors

- **Enforce module boundaries strictly:** Prioritize boundary invariants—module
  entrypoints (`foo.ts`, `foo-meta.ts`), GN `visibility` and dependency edges,
  strict `core -> models -> ui -> panels` layering, `SettingDescriptor`
  placement in the lowest layer where used, public widget/component APIs
  (`DEFAULT_VIEW` input/output contracts), CDP protocol contracts, and test
  validity.
- **Avoid uncodified interior style nits:** Do not flag subjective stylistic
  preferences inside module interiors unless backed by a lint rule or an
  explicit rule under `.agents/rules/`.

## 4. Shared False-Positive Guards

Check these guards before reporting any finding (including general review
findings):

- **Lit `@SomeEvent=${handler}` bindings on `<devtools-widget>` (or a
  widget's `element`):**
  - **Do not flag** `@SomeEvent=${handler}` as "never fires" or "lowercased
    by the HTML parser" when the child widget class is built with
    `Common.ObjectWrapper.eventMixin(...)` on top of `UI.Widget.Widget` /
    `UI.Widget.VBox` / `UI.Widget.HBox`:
    1. `eventMixin.dispatchEventToListeners` (`front_end/core/common/Object.ts`)
       also calls `this.dispatchDOMEvent(new CustomEvent(eventType, {detail: eventData[0]}))`,
       and `Widget.dispatchDOMEvent` dispatches it on `widget.element` (which
       is the `<devtools-widget>` host element when instantiated with `widget()`).
    2. Lit preserves the exact case of `@`, `.`, and `?` binding names by
       reading the original template strings (`attrNames[]` in
       `front_end/third_party/lit/lib/lit.js`), not the lowercased attribute
       names from the HTML parser. So `@PaintProfilerRequested` registers
       `addEventListener('PaintProfilerRequested', ...)`, and `event.detail`
       carries the first payload argument.
  - **Do flag** it when:
    1. The event source extends `Common.ObjectWrapper.ObjectWrapper` directly
       or holds one by composition instead of `eventMixin` on `UI.Widget` (it
       has no `dispatchDOMEvent`, so no DOM `CustomEvent` is fired).
    2. The listener is attached on an ancestor element above the widget's
       host element (`new CustomEvent(...)` in `Object.ts` does not set
       `bubbles: true`).
    3. The `@SomeEvent` handler reads `(event as any).data` instead of
       `(event as CustomEvent<T>).detail`.
- **Multi-line `html` template whitespace (`front_end/ui/lit/strip-whitespace.ts`):**
  - **Do not flag** newlines and indentation spaces between expressions and
    inline elements in multi-line `html` templates from `ui/lit/lit.js`.
    DevTools' custom `html` tag strips `\n\s*` outside `<...>` tags at
    runtime.
- **Generated `.css.js` imports in `<style>${styles}</style>`:**
  - **Do not flag** interpolating `*.css.js` default imports into `<style>`
    in Lit templates. Generated `.css.js` files export plain CSS strings, not
    `CSSStyleSheet` objects.

## 5. Test correctness (the most common review feedback)

- **Tautological tests:** A test must exercise real production code. If a
  mock does the thing the test asserts (for example, a mocked `DOM.undo` that
  calls `removeSection()` directly, followed by an assertion that the section
  was removed), the test checks the mock and nothing else. Mock the *boundary*
  instead (for example, have the CDP stub emit `CSSModel.Events.StyleSheetChanged`)
  and let production code react to it.
- **Vacuous tests:** Look for local promises or data that are never connected
  to DevTools logic, or stubs (like `initialize`) that skip the code path under
  test. These tests pass because nothing happens.
- **Assertions that check the setup:** For example,
  `assert.isNull(pane.node())` right after `pane.setNodeForTest(null)`. Each
  assertion should verify the behavior that the test name describes.
- **Test lives where it belongs:** A test in `Foo.test.ts` should exercise
  `Foo`. Move logic-only tests to the model's test file (for example,
  `CSSMatchedStyles.test.ts`). Otherwise, render the UI and assert on the DOM.
- **Test covers the scenario it claims:** For example, an "iframe event
  listeners" test must select a node *inside* the iframe. It is not enough
  that it passes on `<body>` of the main frame.
- **Right suite:** Ask whether an E2E test could be a unit test, or whether the
  E2E coverage is intentional for a user story. See `devtools-testing-guidance`.
- **E2E selectors match real UI:** Labels and `aria-label`s must match the
  actual strings, for example "Show user agent shadow DOM" and not "User agent
  shadow DOM". Check that the setting being toggled actually affects the
  scenario.
- **Fail fast:** Throw or assert when a required value is missing. Don't let
  the test time out later.
- **Pre-migration tests for legacy widgets:** When reviewing tests added ahead of
  replacing a legacy widget (`TreeOutline`, `DataGrid`, `ListControl`,
  `ListWidget`), check that DOM/tree inspection is encapsulated in local test
  helpers (`dumpTree()`, `findTreeItem()`, `activateRow()`) rather than
  repeated across every `it()` block, and ask for `assertScreenshot(...)` golden
  tests so visual regressions are caught independently of the legacy widget
  implementation.

## 6. Test hygiene and cleanup

- Pair every `beforeEach` singleton creation with a cleanup in `afterEach`
  (for example, `CSSWorkspaceBinding.removeInstance()` or
  `WorkspaceImpl.removeInstance()`) so that state does not leak between tests.
- Restore fake timers in `try { … } finally { clock.restore(); }`, or use the
  sandbox or cleanup that the test runner provides. Keep the scope of fake
  timers small.
- Don't stub the same method twice without calling `restore()` first. Sinon
  throws `Attempted to wrap … which is already wrapped` when the object is the
  same instance.
- Remove guards that were copied from helpers for no reason (for example,
  `if (!stub.called) …` in a test that stubs the method only once).

## 7. Code clarity

- Don't take detours to reach a value. If a module is imported, call
  `TextUtils.TextRange.TextRange.fromObject(...)` directly instead of going
  through `rule.style.range.constructor`.
- Look for dead code, leftover debug code, commented-out blocks, pure-whitespace
  diff hunks in non-CSS files, and unrelated formatting churn.
- **Live-code & abstraction checks in UI migrations**: Flag `DEFAULT_VIEW` or
  `*_VIEW` functions that have zero production callers in the CL (unused views
  staged for a later CL), stateless single-row/item child `UI.Widget` subclasses
  where a `LitTemplate` helper in the parent view suffices, and call sites that
  inline non-trivial shared helpers (such as `UI.UIUtils.maybeCreateNewBadge`)
  instead of converting the shared helper to return `LitTemplate`.
- Check that the change stays in scope. Flag unrelated refactors that should be
  split into a separate CL.
- Check for lifecycle issues: event listeners and observers that are added
  without being removed, and async work that continues after a widget is
  detached.

## 8. CL hygiene

- The description explains *why*, including external dependencies (for
  example, "V8 will stop emitting X; this must land first").
- Include a `Bug:` or `Fixed:` trailer, or `Bug: None`. Keep lines under 72
  characters, and keep diffs at or under `350` changed lines (`insertions + deletions`)
  where practical.
- **Descriptive subject lines & live vertical splits**: The first line (`<= 72`
  chars) must describe *what the CL changes functionally*, never which step or
  pass of a migration it is (no `Pass 1:`, `(2/6)`, or `Step 3 of migration` in
  the subject; place stack context in the body if needed). Flag split CLs that
  defer unit tests to a follow-up test-only CL or defer dead-code removal to a
  cleanup-only tail CL.
- **Never add Piper `KEY=VALUE` tags:** Flag any column-0 lines matching
  `TAG=`, `CONV=`, `BUG=`, `FIXED=`, or `MARKDOWN=true`. DevTools commit
  descriptions must use standard Git trailers (`Bug:`, `Fixed:`) only; Piper
  tags break Git trailer parsing and are rejected by `PRESUBMIT.py`. Agent
  conversations should be linked out of band via
  `git config --global cl.upload-conversation-id true`.
- **UI Eng Vision migration completeness & `Fixed:` vs `Bug:`**: Flag
  `Fixed: <id>` on UI Eng Vision migration CLs when core violations remain in
  the target file: legacy `UI.TreeOutline` or `extends UI.TreeOutline.TreeElement`
  subclasses, `UI.ListControl`, `UI.ListWidget`, `UI.InplaceEditor`, non-MVP
  constructors (missing `element?: HTMLElement` or injectable `view = DEFAULT_VIEW`),
  missing `static override readonly INJECT` for Universe dependencies, custom
  `#renderView()` helpers bypassing `override performUpdate()` +
  `this.requestUpdate()`, constructor-bound model/setting listeners instead of
  non-destructive `wasShown()`/`willHide()` subscriptions, synchronous
  `this.performUpdate()` calls in presenter methods, or TypeScript `private`
  fields not required by `legacy_test_runner`/`blink/web_tests`. Note
  explicitly that a clean `@devtools/no-imperative-dom-api` lint pass does
  **not** prove completeness because ESLint misses `TreeElement` subclasses and
  `UI.ListControl`. Intermediate CLs in a multi-CL migration must use
  `Bug: <id>`, reserving `Fixed: <id>` for the final CL.
- **Component contract preservation**: Flag feature or panel migrations that
  widen `front_end/ui/legacy/` component contracts (such as exporting internal
  classes or turning `*ForTest()` or `*ForTesting()` methods on `Treeoutline.ts`
  into public APIs).
- Disabled tests reference a bug.
- Presubmit, lint, and format pass. See `devtools-verification`.

## 9. Writing review comments

- Be specific: cite file and line, explain the concrete failure mode (such as
  a leak, a hang, or "passes vacuously"), and suggest a fix. Include a code
  snippet when it helps.
- Separate blocking issues from nits and questions (for example, "Should we
  move this to a unit test?").
- When a reviewer's concern is not an actual bug, reply with the rationale.
  Don't make a silent change.
```

## File: README.md
upstream: https://github.com/chromedevtools/devtools-frontend/blob/main/README.md

```text
# Chrome DevTools frontend

<!-- [START badges] -->

[![npm package](https://img.shields.io/npm/v/chrome-devtools-frontend.svg)](https://npmjs.org/package/chrome-devtools-frontend)

<!-- [END badges] -->

This repository contains the client side of Chrome DevTools. It contains all
the TypeScript and CSS code that runs the DevTools web app.

### Source code and documentation

The source code is on [chromium.googlesource.com].

The [Chromium DevTools documentation] tells you how to do these tasks:

- [Set up] a DevTools frontend checkout.
- Use a DevTools frontend checkout.
- Maintain a DevTools frontend checkout.

The documentation also contains design guidelines and architecture
documentation.

Other documentation:

- DevTools user documentation: [devtools.chrome.com](https://devtools.chrome.com)
- Chrome DevTools Protocol documentation: [chromedevtools.github.io/devtools-protocol](https://chromedevtools.github.io/devtools-protocol)
- A list of Chrome DevTools resources: [github.com/paulirish/awesome-chrome-devtools](https://github.com/paulirish/awesome-chrome-devtools)
- How to contribute to Chrome DevTools: [goo.gle/devtools-contribution-guide](http://goo.gle/devtools-contribution-guide)
- How to contribute to the Chrome DevTools Protocol: [goo.gle/devtools-contribution-guide-cdp](https://goo.gle/devtools-contribution-guide-cdp)

### Source mirrors

There is a mirror of the DevTools frontend repository on
[GitHub](https://github.com/ChromeDevTools/devtools-frontend).

The DevTools frontend is also available on npm as the
[chrome-devtools-frontend](https://www.npmjs.com/package/chrome-devtools-frontend)
package. The package does not supply CJS modules or ES modules. Thus, it can be
difficult to use this package in other tools. For an example of how to use it,
see [this file](https://github.com/paulirish/devtools-timeline-model/blob/master/index.js).

The version number of the npm package (for example, `1.0.373466`) is the
Chromium commit position of the latest frontend Git commit. The version number
increases with each Chromium commit. But we publish the package only
approximately one time each day.

### Contact us

- Follow [@ChromeDevTools] on X (previously Twitter).
- Send a message to the Chrome DevTools mailing list: [g/google-chrome-developer-tools]
- Report a new DevTools bug: [goo.gle/devtools-bug]

### Get the latest news

To get the latest news about DevTools development, do one or more of these
steps:

- Read [What's new in DevTools].
- Read [Umar's Dev Tips].
- Follow these accounts on X:
  [@umaar](https://x.com/umaar),
  [@malyw](https://x.com/malyw),
  [@kdzwinel](https://x.com/kdzwinel),
  [@addyosmani](https://x.com/addyosmani),
  [@paul_irish](https://x.com/paul_irish),
  [@samccone](https://x.com/samccone),
  [@mathias](https://x.com/mathias),
  [@mattzeunert](https://x.com/mattzeunert),
  [@PrashantPalikhe](https://x.com/PrashantPalikhe),
  [@ziyunfei](https://x.com/ziyunfei), and
  [@bmeurer](https://x.com/bmeurer).
- Join the [g/devtools-reviews@chromium.org] mailing list. This list shows all
  pending code reviews.
- Read the [commit log], or follow [@DevToolsCommits] on X.
- See [all open DevTools bugs] on crbug.com.
- Use Chrome Canary and try the experiments.

  [Chromium DevTools documentation]: http://goo.gle/chromium-devtools
  [set up]: https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/get_the_code.md
  [chromium.googlesource.com]: https://chromium.googlesource.com/devtools/devtools-frontend
  [What's new in DevTools]: https://developer.chrome.com/docs/devtools/news
  [Umar's Dev Tips]: https://umaar.com/dev-tips
  [g/devtools-reviews@chromium.org]: https://groups.google.com/a/chromium.org/forum/#!forum/devtools-reviews
  [commit log]: https://chromium.googlesource.com/devtools/devtools-frontend/+log/main
  [@ChromeDevTools]: http://x.com/ChromeDevTools
  [@DevToolsCommits]: http://x.com/DevToolsCommits
  [all open DevTools bugs]: http://goo.gle/devtools-bugs
  [g/google-chrome-developer-tools]: https://groups.google.com/forum/#!forum/google-chrome-developer-tools
  [goo.gle/devtools-bug]: http://goo.gle/devtools-bug
```
