Aglet

Triage Pagination Gaps in Lists and Batches

A pagination gap occurs when a traversal skips, repeats, or prematurely stops over a result set. Triage should capture the page contract, ordering key, cursor or offset, filters, and snapshot timing. Compare identifiers across adjacent pages before choosing whether the issue is data or traversal logic.

Establish what is happening

  1. Write the page contract

    Record page size, offset or cursor format, ordering fields, tie-breaking rule, filters, inclusion of boundaries, and termination condition. Note whether the source can change during traversal. Preserve the exact request inputs and response metadata for each observed page.

  2. Compare adjacent pages

    Collect identifiers from consecutive pages and classify missing, repeated, reordered, and unexpectedly terminal records. Inspect the last item and next cursor together. Check whether a filter or sort key changes between requests, including implicit defaults or mutable values.

  3. Bound the gap

    Recount the expected population under the same filters and snapshot, then compare traversed identifiers and page totals. Locate the first skipped or repeated boundary and record source, page number, request time, and processing revision. Separate a moving dataset from a deterministic gap.

What to carry forward

Deliver a pagination scope brief with the traversal contract, first divergent boundary, missing or repeated identifiers, affected filters, and snapshot limits. Triage stops when another engineer can reproduce the page sequence. Keep the scope provisional if the source changed during traversal and no stable comparison exists.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow