Ordering guide

How to arrange a pull request's changed files into a reading order for reviewers. It applies to people using arrange mode and to AI agents, which receive this page from the get_ordering_guide tool.

The goal: a reviewer who reads top to bottom always meets a piece of code after the things it depends on, and understands why each group of files changed.

Workflow for agents

  1. Call get_pull_request with the owner, repo and number. It returns every changed file, the current saved order (if any) and its version.
  2. Understand the change. If you are running inside a checkout of the repository, read the diff and the surrounding code there (for example git diff <base>...<head>); that gives far better results than patches alone. Otherwise call get_pull_request again with include_patches: true.
  3. Build the order following the rules below.
  4. Call save_reading_order with base_version set to the version you received (0 when there was no order). If it reports missing or unknown paths, fix the list and save again. If it reports a conflict, someone else saved in the meantime: fetch again, and only overwrite if the user wants that.
  5. Tell the user the review link returned by the save.

Ordering rules

Order by dependency: a file comes after the files it uses, before the files that use it. When there is no dependency between files, use these layers, top to bottom:

  1. Contracts and switches: feature flags, remote config, constants, API schemas, database migrations, public interfaces, event names.
  2. Models and types: data classes, DTOs, enums, type definitions.
  3. Core logic and utilities: pure functions, parsers, algorithms, helpers the rest builds on.
  4. Storage and data access: repositories, caches, persistence, network clients.
  5. Application logic: controllers, services, view models, use cases, state holders.
  6. Presentation: views, components, adapters, screens, templates.
  7. Wiring: dependency injection, routing, entry points, platform glue that only connects the pieces above.
  8. Resources: layouts, drawables, styles, strings, dimensions, assets, translations. Put the main screen layout before the small pieces it includes.
  9. Build and tooling: build scripts, CI, lint config, generated files, lockfiles.

Tests go directly after the file they test, not in a separate block at the end, unless a test covers many files at once; then put it after the last of them.

Other rules:

  • Deleted files go next to the file that replaced them, so the reviewer compares old and new together.
  • A renamed or moved file with no real changes goes in the Build and tooling section or the last section.
  • If one file is the heart of the change, it may come first with a note, even if it depends on small files; say so in the section note.
  • Every changed file appears exactly once. Do not invent paths.

Sections

Group the files into 3 to 8 sections. A very small pull request (under 5 files) can use one section or none.

  • Title: a short noun phrase naming what the group does in this change, such as "Feature flag and analytics events" or "Storage works on groups". Not a file type ("Kotlin files") or a layer name alone ("Models").
  • Note: one to three plain sentences saying what changed and why, and anything the reviewer should keep in mind. Name concrete classes, functions or flags in backticks. Don't restate the file list.

File notes

Add a note to a file only when it helps the review: a non-obvious reason, a risk, a follow-up, or "mechanical rename, skim". Most files need no note. Keep notes to one or two sentences.

Focus labels

A file can carry one focus label:

  • key: the heart of the change, where most of the review effort should go. Use it for one to three files, never most of them.
  • skim: mechanical or low-risk, such as renames, string changes and simple wiring.
  • generated: generated, vendored or lock files. They start collapsed for reviewers.

Leave most files without a label.

Checklists

Checklist items tell the reviewer what to verify. Add them to a section or file when there is something specific and checkable:

  • Good: "With the flag off, the list is identical to before", "removeRecentClipGroup also deletes the extracted clips", "Back key closes the highlight before the page".
  • Bad: "Code looks good", "Check for bugs", "Review this file".

Use 0 to 4 items per section and at most one or two per file. Keep each item under 120 characters.

Style

Write for a busy reviewer: short, specific, no filler, no marketing tone, no emoji. Use the terms the code uses.

For LLMs and agents: This page as Markdown llms.txt llms-full.txt