Arranging a pull request

The author of a change knows the order it makes sense in. Arrange mode is where you write that down.

#Who can arrange

Anyone with write access to the repository (push, maintain or admin on GitHub) can save an order. Everyone who can read the repository can see it. LogiKFlow checks your permission with GitHub on every save.

#Open arrange mode

On the pull request page, choose Arrange files. Every changed file is listed, in the current order or alphabetically if nothing is saved yet.

• Move a file or section: drag it by the handle (⋮⋮), or use ↑ and ↓. The arrows work with the keyboard too.
• Add a section: Add section puts a new section at the top. Give it a title, then move it where it belongs. Files below a section belong to it until the next section.
• Remove a section: Remove deletes the section header. Its files stay where they are.
• Split a file: Split · N on a file with several changes turns it into one part per change, so you can place each part in the section where it belongs. See Split a file across sections.
• Start over: Reset to alphabetical removes all sections, merges split files and sorts the files by path. Notes and checklist items on files are kept.

Nothing changes for reviewers until you choose Save order. Cancel or Esc discards your edits.

#Overview

The box at the top of arrange mode holds an overview for reviewers: two or three sentences on what the change does, how to read it, and where the risk is. Reviewers see it above the first section and at the start of one-change mode, and Post to PR puts it in the comment. Leave it empty for a tiny pull request.

#Sections

A section groups files that change for the same reason. Good sections make a large pull request feel like a short story:

Three to eight sections suit most pull requests. The ordering guide has the full rules.

Pick a layer for a section from the menu next to its title (contracts and switches, models and types, core logic, storage, application logic, presentation, wiring, resources, build and tooling). Reviewers see it as a label, and Check order uses it to spot layers out of order.

#Notes

Sections and files can have a note, shown above the section or the file's diff. Use notes to say why, which the diff can't show:

• the reason behind a non-obvious choice;
• what to watch out for;
• that a file is a mechanical rename and can be skimmed.

Wrap code in backticks, for example `invitesEnabled`, to show it as code.

#Focus labels

Give a file a focus label from the menu next to its path:

• Key file: the heart of the change. It's highlighted for reviewers.
• Skim: mechanical or low-risk.
• Generated: generated or vendored output. It starts collapsed.

Most files need no label. Use Key file for one to three files at most, or it stops meaning anything.

#Split a file across sections

A file sometimes holds changes that belong to different sections, such as a shared router or strings file that gets a small addition for each feature. Instead of explaining that in a note, split it:

1. Choose Split · N on the file. It becomes N parts, one per change, each showing the line it starts at and its first changed line.
2. Move each part to its section with drag and drop, the arrows or Move to…. Parts can hold one change or several.
3. To regroup, drag a change by its row: drop it on another part of the same file to join that part, or between any files or on a section to make a new part there. Move… next to each change does the same from the keyboard. A part left with no changes is removed, and its note and checklist move with the change.
4. Give a part its own note, checklist or focus label if it needs one.

To undo, choose Merge parts on the file's first part. The parts join back into one card, keeping their notes and checklist items.

Split only when it helps. A reviewer reads most files best in one piece.

Reviewers see each part as its own card, labelled Part 2 of 3, with only that part's changes. Viewed is still per file: ticking any part ticks them all. If a later commit adds a change to a split file, it appears in the file's first part.

#Writing for one-change-at-a-time review

Reviewers can step through the order one change (diff hunk) at a time. Your section note and file note stay on screen above each change, so:

• put what a reviewer needs for the whole file in the file note;
• when a file mixes several unrelated edits, list them in the note in the order they appear.

#Checklists

Add checklist items to a section or a file for things a reviewer should verify:

• "With the flag off, the list is unchanged"
• "Accepting an invite also closes it"
• "Back button closes the dialog before the page"

Each reviewer ticks their own boxes. Everyone sees who checked each item (✓ amal, octo), and each section shows how many items you've checked. Items keep their identity when you move files around or edit other parts of the order, so ticks aren't lost.

Avoid vague items such as "Check for bugs". If an item can't be verified, it doesn't belong on the list.

#Check order

Check order compares your draft with the ordering guide and lists tips: a section title that is only a layer name, a key file without a note, a test placed before the file it covers, a file placed before one it imports, a generated file without its label, and more. Tips never block saving; apply the ones that fit. AI agents get the same tips when they save.

#When two people arrange at once

LogiKFlow uses versions. If someone else saves an order while you're editing, your save is stopped and you choose:

• Load their order: discard your edits and start from theirs.
• Overwrite with mine: save yours as the new version. Theirs stays in history.

#History and restore

History lists every saved version with who saved it, when, and whether an AI agent saved it. Restore saves an old version again as the newest one, so nothing is ever lost.

#Review progress

The people button in the toolbar shows who has started reviewing, how many files each person has viewed (counting only files that haven't changed since), and how many checklist items they've ticked.

#New commits after arranging

When commits are pushed after the order was saved, a banner says so and how many changed files aren't in the order yet. If you have write access, it offers Arrange files, and Copy agent prompt, which copies a one-line request you can paste into your agent to re-arrange.

The order stores file paths, so it survives new commits:

• Files you already placed keep their position. Parts of split files keep their changes, because each change is recognised by its content, not its line numbers.
• Files added to the pull request later appear at the end, under Not in the saved order. Arrange again to place them.
• Files removed from the pull request disappear from the order.

#Post the link to the pull request

Post to PR adds a comment on the GitHub pull request with the review link, the overview, the list of sections with their layer and size, and the key files. It's posted as you, and needs the Pull requests: write permission on the app installation.

After the first post, the button becomes Update PR comment. It edits the same comment instead of adding a new one, so re-arranging never clutters the pull request. If the comment was deleted, or someone else posted it and you can't edit it, a new comment is posted.