What AI Code Review Taught Us About Analytics Contracts

The first version of an analytics feature can look complete long before the data path is. During one review cycle, a filter appeared active even though its value never reached the request. A pagination cap made the final page ambiguous. Timestamps shifted depending on which timezone interpreted them.

AI-assisted code review helped surface these gaps. The deeper lesson was about the work around the reviews: we had described the visible experience in detail, but spent less time defining the contracts between the URL, UI state, server request, API response, and rendered data.

That gap turned implementation into a series of review cycles. It also gave us a practical way to improve: define the contracts early, test their boundaries, and turn review findings into rules the system can keep.

A feature brief can describe the main components, controls, loading behavior, and empty states. That gives the team a clear product target. The less visible questions still need answers:

• Which filters does the API support?
• What happens to cached rows when someone changes workspace or source?
• How should a timestamp without an offset be interpreted?
• Where does the application reject a date range that is too large?
• What should the UI say when a result limit prevents people from reaching every record?

These are product questions as much as implementation questions. When a control appears to filter a report, people expect the returned data to reflect it. When the workspace changes, they expect the previous workspace’s rows to disappear. When a chart and a table describe the same event, they expect the timestamp to agree.

We had enough detail to build the visible experience. We also needed a short, shared agreement for the behavior behind it: which layer owns each rule, which values cross the boundary, and what a user should see when a limit applies.

A filter can exist in several places at once: as a selected control value, a URL parameter, a server request field, and an API condition. Those representations have to stay aligned.

During this work, some controls could appear active even though their values were missing from the Events request. The page could reload with a selected filter and still return unchanged analytics. That is a trust problem: the interface promises a result the data path does not deliver.

Encoding can introduce another mismatch. Event names are user-controlled strings, so punctuation such as a comma may be part of a valid name. If a client treats that punctuation as a separator, one selected event can become two filters. A shared URL helper can create a similar surprise if another report interprets the same value differently.

For every control, ask: can we trace the selection to the exact request field and see where the API applies it? If not, the control needs a supported request path, a narrower scope, or clearer behavior. A focused test can follow the whole route from URL state to request construction and confirm that punctuation survives a round trip.

Pagination looks simple until a server limit does not line up with the client’s page boundaries. If the client advances past a capped offset and the server clamps it, the last request can repeat records or overlap the previous page. Users see duplicate rows while the interface presents them as separate pages.

A pagination contract should define the page size, maximum reachable offset, boundary behavior, and how the interface describes a cap. Test the final reachable page: calculate its range, confirm it does not overlap an earlier page, and make any remaining limit understandable. A token-based design can make continuation clearer; Google’s pagination guidance is one example of documenting page-size limits and next-page behavior.

Time has a similar boundary problem. A timestamp with an explicit offset identifies an instant. A timestamp without one is a wall-clock value whose timezone must come from the contract. JavaScript’s built-in parser treats standard date-time strings without an offset as local time on the viewer’s device, so relying on it can make the same report value appear differently across users. MDN documents this parsing behavior; RFC 3339 also explains why unqualified local time is ambiguous for Internet timestamps.

If a report defines an offset-less value in its own timezone, every layer should preserve that meaning. The chart, table, detail dialog, and API adapter should agree on the instant or wall-clock value they are showing. Test the same event in more than one timezone rather than assuming the browser’s local timezone matches the report.

An automated review is most useful when a finding becomes something the team can preserve. A comment about stale rows can become the invariant, “changing workspace scope clears the previous result.” A comment about the final page can become, “adjacent pages never overlap.” A timestamp comment can become, “offset-less report values keep their documented timezone meaning.”

That translation changes the review loop. Instead of fixing only the line mentioned in a comment, the team can inspect the assumption behind it and test that assumption at the boundary.

A compact test matrix for a report feature might cover:

• Each visible filter changes the request as intended.
• Scope changes clear previous rows and details.
• Event names round-trip without losing punctuation.
• The final reachable page does not overlap an earlier page.
• Date limits are checked before expensive requests.
• Chart and table timestamps agree in more than one timezone.
• A pending sort cannot leave the grid and server with different state.

These tests give future reviewers a clearer target. They can check the product contract instead of rediscovering one edge case at a time.

Before implementation, I will map the path from control to data: URL state, server loader, request schema, API behavior, response, and rendering. For each control, I will record which contract owns it and which neighboring reports could be affected by shared helpers.

Then I will build the feature in reviewable slices and add boundary tests as each contract becomes real. When review comments arrive, I will group them by root cause, update the invariant, and add a regression case. Some comments will become outdated as the code changes; the assumption behind them can still improve the test plan.

The goal is not to avoid review findings. It is to make fewer important assumptions invisible in the first place. What contract would you write down before building your next data-heavy interface?