Release Notes Built From Reviewed Records

Nineteen records, thirty days, one session that ran 38 hours and 27 minutes, and when it closed nobody had loaded the deployed page. That last part is the honest state of this build, so I’ll start there and work backward.

The old page described groups, not changes

The release candidates page in our staff portal used to render one auto-generated blurb per feature group. Tickets were bucketed by group, a model summarized each bucket, and the page showed the summary. Every field on it was derived, and nobody had looked at any of it before it went up.

We ran that approach for a while, and it failed the way you would predict once you read a few entries. A blurb that summarizes a group of tickets describes the group. A reviewer deciding whether a release candidate is safe to cut needs to know what one change does to one screen. The blurbs were fluent and plausible, and they gave the reviewer nothing to check against. People stopped reading the page, because a summary you cannot verify is just a paragraph.

One record per shipped change

The rebuild flips the grain. There is one record per shipped change, and each record has fixed parts:

• a plain title, written for someone who has not seen the ticket
• a “why it matters” line
• a ticket table listing every ticket behind the change
• screenshots that show the actual change

The screenshots are the part I care about most. A description can be wrong and still read well. A screenshot of the changed screen either shows the change or it does not.

The first backfill covers the last thirty days and comes to nineteen records. Nineteen is small enough that a human can read all of them in one sitting, which is the property the old page lost.

Checking the tables from the tracker side

Every ticket table was checked against live JIRA by a separate pass, not by the session that wrote the records. The session that authored a record has every incentive to trust its own ticket ids, so the checker starts from JIRA and works toward the record. It asks whether each ticket exists, whether it maps to the change described, and whether its status matches what the page claims.

That check is what lets the ticket table mean something. Without it, a record is a well-formatted claim. With it, a record is a claim with a receipt.

Green CI, unloaded page

The work went to the review branch with CI green. Then the session closed with this in its own summary: the deployed page had not been loaded, so the review lane was not yet confirmed.

I am keeping that sentence in the post because it is the real edge of what I know. CI green tells me the code builds and the tests pass. It does not tell me the page renders nineteen records with working screenshots on the environment a reviewer will open. Those are different claims, and the agent that closed the session reported the gap instead of rounding it up to “shipped.”

There is a smaller version of the same limit elsewhere in that day’s logs. One of the agents building a status page tried to capture a screenshot and reported that no headless browser was available, no playwright, selenium or chromium binary, and that it was skipping the capture as its fallback instructed. A screenshot-driven page is only as trustworthy as the pipeline that produces the screenshots, and on that machine the pipeline was missing. Reporting the gap was the correct behavior. It also means the first real test of the release page is a human loading it.

Copying the shape

If you want to reuse this design:

1. Pick the unit a reviewer decides on. For us that is one shipped change, and a feature group is too coarse.
2. Give the unit required fields, so a record with no “why it matters” or no screenshot is visibly incomplete instead of quietly thin.
3. Store tickets as a table under the record. Ticket ids are the join key back to the tracker.
4. Run verification from the tracker side, in a separate pass, and have it check the join key in both directions.
5. Treat “CI green” and “page loads in the target environment” as two gates. Do not let the first stand in for the second.

Step five is the one I would have skipped if the summary had not refused to skip it for me.

What is still open

The reviewer has not yet confirmed the page. If a screenshot turns out to point at the wrong build, or a record’s ticket table drifts from JIRA between verification and review, the design has a hole I have not found yet. Nineteen records is enough to find out quickly. I would rather learn that from one person reading one page than from a release cut off a summary nobody could check.

dxdev LESSON · paste into your AI coding agent
LESSON: Separate Verified Change Records From Target Environment Review
SOURCE: dxdev.com/blog/2026-09-26_release-notes-from-reviewed-records
WHAT HAPPENED: The former page grouped tickets and published model written summaries that reviewers could not meaningfully verify. The rebuild created one record for each shipped change, with a title, a why it matters line, a ticket table, and screenshots. A separate pass started from live JIRA to verify ticket existence, the mapping to each change, and the claimed status. CI was green on the review branch, but the deployed page had not been opened, so the review lane remained unconfirmed. Logs also recorded that one screenshot capture could not run because the machine lacked a headless browser pipeline.
THE RULE: Make the unit of release review a single change with evidence a reviewer can inspect, then verify its tracker links independently. Treat successful CI and a page loading with its evidence in the target environment as separate required gates.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. Does every release record represent one shipped change rather than a broad ticket group?
      2. Does every record include a why it matters line, a complete ticket table, and screenshots of the actual change?
      3. Has an independent tracker side check verified ticket existence, change mapping, and status, and has someone loaded the page in the target environment?
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.