# ihumane · Code review · v0.1 You are an agent about to review a code change: someone else's pull request, a colleague's branch, or your own change before you hand it over. This module is written for you, not for a human reader. It turns what senior reviewers do by habit into rules you can follow and checks you can run. Read this file fully. Read the other files when the step below tells you to. Writing the code is Code craft. This module is about judging a change and telling a person what you found. Where a Code craft rule already says what good looks like, this module points to it by its ID (for example Code craft V2) instead of repeating it. --- ## Why this exists A review is the last time a person looks closely before a change reaches users. People trust it: a reviewer's "approved" means "someone careful read this". You can read a 900-line diff in seconds, which makes it easy to look careful without being careful. Agents fail at review in three ways: 1. **They nitpick and miss the bug.** Ten comments about names and spacing, and none about the loop that skips the last item or the delete with no `where` clause. The author fixes the ten, the bug ships, and the review looked thorough. 2. **They say "looks good" without running anything.** The tests weren't run, the branch wasn't checked out, the one call to a function that doesn't exist was read and believed. "LGTM" with nothing behind it is worse than no review, because people stop looking. 3. **They rewrite the change instead of reviewing it.** A "suggestion" that replaces the author's 40 lines with 80 of yours, or a new commit pushed to their branch. The author can't tell what was wrong with theirs, learns nothing, and now has to review your code. The reader of your review is a person: the author who has to act on it, and whoever decides whether to merge. Every rule here is about what they can do with what you wrote. --- ## Size the job first | Size | Looks like | Do | |---|---|---| | **Small** | A fix inside one function, a config change, a dependency bump, a copy change, under about 100 changed lines | Read the description and know what it's for (I1). Read the change with the riskiest question first (D2). Run the tests, or say you didn't (D3). Label what you find (W1). One short summary with a verdict (F1). Skip the reading-order map and the lenses. | | **Large** | A feature across several files, a migration, a change to an interface other code uses, anything touching sign-in, payments or stored data, or anything over about 400 changed lines | The full workflow below, every step. Run `checks/diffmap.js` first to see the shape of the change. If it's too big to review well, say so before you start (D6). | If unsure, treat it as small. Running it is never skipped: a review that didn't run anything says so in its first line. --- ## The workflow | Step | What you do | File | |------|-------------|------| | 1. Understand | Find out what the change is for, what kind of review is wanted, how risky it is, and what this project's rules are. | `1-understand.md` | | 2. Read | Read in a useful order, run it, look for harm before style, look for what's missing, and read AI-written code with extra care. | `2-read.md` | | 3. Comment | Write comments a person can act on: labelled, located, explained, with a fix, as sure as you really are. | `3-comment.md` | | 4. Your own work | Review your own change before asking anyone, and answer review comments on it well. | `4-own-work.md` | | 5. Report | Check your review through four lenses, then give one summary with a verdict and what you covered. | `5-report.md` | When you're reviewing your own change before handing it over, start at step 4, then use steps 2 and 5 on it. --- ## The format of every rule Rules in this module use the same fields: - **Rule:** what to do, as specifically as possible. - **Why:** what happens to a real person if you don't: the author, the person who merges, the user, or the next developer. - **Agent trap:** the specific way agents like you get this wrong. - **Check:** how to verify it, ideally something you can run or count. - **Limit:** where the rule stops, on rules that could be taken too far. Runnable checks live in `checks/`. Run them; don't trust your skim of the diff. | Check | Finds | |---|---| | `checks/diffmap.js` | The shape of a change: its size, a reading order (tests, interfaces, migrations, core, config, the rest), and what to look at closely: code changed with no test changed, migrations, removed or changed exports and how many places still use them, new dependencies, imports of packages the project doesn't have, tests that mock the file they test, risky areas. Node, no dependencies. Reads `git diff`, a saved diff, or `gh pr diff`. | | Code craft `checks/tidy.js` | Leftovers in the changed lines: debug logs, `.only` and `.skip`, empty catch blocks, likely secrets, TODOs, commented-out code. Run it with `--diff main` on the branch you're reviewing. | --- ## Five rules that matter most If you remember nothing else: 1. **Know what it's for before you judge it.** Read the ticket and the description first. A change can be well written and still not do what was asked. (`1-understand.md` I1) 2. **Harm before style.** Lost data, a security hole, wrong results and broken callers come first. Names and spacing come last, or not at all. (`2-read.md` D2) 3. **Run it, don't read it and believe it.** Check out the branch, run the tests, call the code. Say what you ran. (`2-read.md` D3) 4. **Every comment says how much it matters, and what to do.** Blocking, should fix, nit or question, with the place, the problem, the reason and a fix. (`3-comment.md` W1, W2) 5. **Say what you didn't cover.** A review that says "I read the API changes, not the front end" is useful. One that implies it read everything, and didn't, is a trap. (`5-report.md` F2) --- ## Precedence The person's instructions and the project's own review rules come before this module: a `CONTRIBUTING.md`, a pull request template, a review checklist, labels the team already uses for severity, or a rule that only certain people approve. If a rule here conflicts with them, follow them, and mention the conflict once in your summary. Posting a review is speaking for the person in front of their colleagues. Unless they asked you to post, show them the review first (F3).