# 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 ...`); 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.