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, and repoConventions when the repository has a .github/logikflow.md file. Follow the repository's conventions: where they conflict with this guide, they win. Add their checklist items to the most relevant section.
  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. Files with more than one change also carry changes, with an id for each change; you need these only to split a file across sections.
  3. Build the order following the rules below: an overview, sections with a layer, and files in dependency order. Use the reading hints on each file to check yourself.
  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. If the result lists suggestions, apply the ones that fit and save once more with the new version. One revision is enough: see Suggestions.
  6. Tell the user the review link returned by the save.
  7. Follow the save result's nextStep about a diagram. Diagrams are optional: see Diagrams.

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.

A section can name its layer with layer: contracts, models, logic, storage, app, ui, wiring, resources or tooling, in that order. Reviewers see it next to the section title, and the save checks that layers come in order.

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, unless you split it (below). Do not invent paths.

Reading hints

get_pull_request adds up to three hints to a file when it can work them out. They come from paths and from the import lines visible in the diff, so treat them as a starting point and confirm against the code.

  • dependsOn: changed files this file imports. A file should come after everything in its dependsOn, unless a note says why not. Imports that didn't change aren't in the diff, so the list can be incomplete.
  • testOf: the changed file this test covers, from naming conventions such as foo.test.ts, FooTest.kt, test_foo.py and foo_test.go. Put the test directly after that file.
  • likelyGenerated: a lockfile, or minified, vendored or generated output. Label it generated.

Overview

Write an overview of two or three sentences. Reviewers read it before the first section, it opens one-change mode, and it goes into the pull request comment. Say:

  1. what the change does, in one sentence that isn't the pull request title;
  2. the reading path: "Start with the flag and migration, then the service, then the dialog";
  3. where the risk is, or what to read slowly: "The retry loop in InviteService is the part to check."

Skip it only for a tiny pull request where the section notes already say everything.

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 schema" or "Invites are stored per team". Not a file type ("Kotlin files") or a layer name alone ("Models"). Read your titles top to bottom: together they should tell the story of the change.
  • Layer: the layer from Ordering rules this section belongs to, when one fits. Reviewers see it as a label next to the title.
  • Note: one to three plain sentences saying what changed and why, and anything the reviewer should keep in mind. When it isn't obvious, open with how this section builds on the previous one: "Uses the invitedAt field from Part 1." 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.

Reviewers can step through a pull request one change (diff hunk) at a time, and they see the file's note above every change in that file. When a file holds several unrelated changes, say so in the note and name them in the order they appear, for example: "Two changes: the new invitesEnabled check, then the rename of listMembers." If those changes belong to different sections, split the file instead.

Splitting a file across sections

Sometimes one file holds changes that belong to different parts of the story, such as a new model field near the top and the screen code that uses it further down. You can split that file so each part appears in the section it belongs to.

Split only when it really helps. Most files should stay whole: a reviewer reads a file more easily in one place. Good reasons to split:

  • a shared file (a router, a strings file, a DI module, a large view model) that gets small unrelated additions for several features in the pull request;
  • one change in a file is a prerequisite that has to be read early, and the rest only makes sense later.

How to split:

  1. Take the change IDs from files[].changes in get_pull_request. Only files with two or more changes have them.
  2. List the file once in each section where part of it belongs, with hunks naming the changes for that part, in any order. Each change goes in exactly one part.
  3. Optionally, list the file once more without hunks. That part takes every change you didn't name, including changes from commits pushed later. Without it, every change must be named, and later changes join the first part.

Each part can have its own note, checks and focus. Give each part a short note saying what that part does, for example "Part 1: the new invitedAt field; the screen that shows it is in Invite dialog."

Change IDs come from each change's content, not its line numbers, so they stay the same when other changes move the lines around. If a part names an ID that no longer exists, the save is rejected with the current IDs to use.

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. Every key file needs a note saying what to look for; a key label without one tells the reviewer to read carefully but not what for.
  • 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", "acceptInvite also closes the invite", "Back button closes the dialog 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.

Suggestions

save_reading_order saves first, then checks the order against this guide. The result's suggestions list what would make it easier to follow: a section titled with a layer name, a key file without a note, more than three key files, a vague checklist item, a test placed before the file it covers, a file placed before one it imports, a generated file without its label, a missing overview, and similar. Nothing in the list blocks the save, and get_pull_request shows the same list for the current order.

Apply the suggestions that fit and save once more with the returned version. Skip one when you have a reason, and put the reason in the note it concerns. One revision is enough; don't loop.

Diagrams

A diagram is an optional picture of how the pieces of the change connect. Reviewers open it from the Diagram tab, and each box can open its file or one exact change. Save one with save_diagram; it never touches the reading order.

When to draw one

Follow nextStep from save_reading_order and the repository's diagramPreference from get_pull_request:

  • never: don't offer or draw one.
  • always: draw one for every pull request, without asking.
  • ask (the default): after saving the order, ask the user once whether they'd like a diagram, unless the pull request is small (under 4 files) or they already answered in this conversation. Draw one only if they say yes, or they asked for one in the first place.

A diagram helps when behaviour flows across several files: a request passing through layers, an event and what reacts to it, a state machine, a fallback path. Skip it for renames, dependency bumps, copy changes or a pull request that is mostly one file.

How to draw a good one

  • 4 to 20 nodes. One node is one step or one piece in the flow, not one file. Leave out files that don't take part in the flow (tests can be one node per behaviour they cover).
  • Titles are short verbs or nouns: "Check cycle", "Queue outer boundary", "Invite model". Up to 80 characters; 2 to 4 words is best.
  • kind sets the colour and icon:
    • trigger: where the flow starts, such as a user action, event, request or cron job.
    • logic: code that decides or transforms.
    • decision: a branch point.
    • data: models, storage, caches, migrations.
    • ui: screens, views, components.
    • test: tests that cover part of the flow.
    • config: flags, settings, build and wiring.
    • external: services and libraries outside the repository.
    • warning: a fallback, error path or known risk.
  • lines add up to 4 short label: text rows. Useful labels are change (what this pull request changes here), role, example, returns and why. Keep each under 80 characters and wrap code in backticks.
  • file links the node to a changed file. Add hunk with an id from files[].changes to point at one change. Only use paths and ids from get_pull_request.
  • Edges go in the direction things happen or depend: caller to callee, event to handler, code to the test that covers it. Label them with 1 to 3 words ("walk graph", "covered by", "on error"). Use dashed: true for optional or indirect links.
  • Groups (up to 12) draw a box around nodes that belong together, such as "Server", "Client payload" or "Regression coverage". Use the same names as your sections when they match.
  • Give the diagram a title that says what it shows, such as "How an invite is accepted".

The layout is automatic, left to right, so you only describe the pieces and how they connect. Base base_version on diagramBaseVersion from get_pull_request. When the user asks to redraw, fetch again, start from currentDiagram.diagram and change what's needed.

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