Files
Ansho Rei 19c666b5dc Close a review of landed work by filing its remaining issues as tickets, and bump to 0.33.10
Work already on the default branch cannot go back to committed without
reopening shipped code. The reviewer files each remaining issue as a new
ticket, related issues together, comments why the ticket is closing, and
moves it to done.
2026-11-06 18:43:07 +01:00

12 KiB

name, description
name description
worklane-review Review a finished worklane ticket against the code that claims to close it, and record the verdict on the board. Use when asked to review a ticket, to check whether a ticket is really done, or to verify that an implementation matches its acceptance criteria, whether the ticket is named by id, by title or as "the one in reviewing". Covers finding the commits, judging each criterion against the code, what a reviewer may and may not write back to the board, and how to close a ticket whose work is already on master by filing its remaining issues as new tickets.

Reviewing a worklane ticket

For "review ticket 1b78a24", "is 4179958 actually done", "check the work on the tui scroll ticket". The subject is one ticket. Reviewing a diff that no ticket claims is ordinary code review and not this job.

This document is the review only. The CLI itself, the statuses, how a ticket is addressed and the argument traps, is the worklane skill; read that too.

What a review produces

Steps 1 to 3 are the same for every review. What you write back depends on one question answered in step 2: is the work already on the default branch (master or main)?

Not yet landed (on a branch, or not merged): steps 4 and 5, which produce

  1. One comment on the ticket, in the structure below.
  2. Unticked criteria, for the ones the code does not actually meet.
  3. Appended criteria, for work the review found that the ticket never asked for.

and nothing else. You do not tick a criterion, you do not move the ticket, and you do not fix the code. Each of those has a reason, given where it comes up.

Already landed: skip steps 4 and 5 and follow step 6 instead. The findings become new tickets rather than appended criteria, and the review ends with you moving the ticket to done. You still never tick a criterion and never fix the code.

1. Read the ticket before the code

worklane show 1b78a24

All of it, comments included. The description says what was wrong, the criteria say what "done" was supposed to mean, the plan says what someone intended to do about it, and the comments are where the intent moved after filing. A criterion that contradicts a comment is one of the more useful things you can find: it means the ticket was not updated when the plan changed, and one of the two is now lying to whoever reads the board.

Read the Relations too. A blocked by that has not landed, or a regression of, changes what the change was allowed to do and what the review has to check twice. A ticket reaching review while its blocker is still in review is allowed by the board, so it is normal rather than a fault, and it is exactly the case where the code under review may be resting on work that has not landed: check that it does not assume the blocker is finished.

2. Find the work

The board stores no branch and no sha, so the link from ticket to code has to be found. Check the repo's own commit convention first, in its AGENTS.md, CLAUDE.md or in git log, rather than assuming the id appears in the message at all.

git log --all --oneline --grep 1b78a24        # where commits name the ticket
git log --oneline -20                          # where they do not, read the recent ones
git branch -a --list '*scroll*'                # a branch named after the work
git diff main...HEAD                           # the whole change, once you have both ends

Widen it with the files the description names, since a ticket that names src/tui.rs is reviewable through git log -p -- src/tui.rs even when no commit message mentions it.

Once you have the commits, check whether each one is on the default branch. This decides whether you go on to steps 4 and 5 or to step 6, so settle it now:

git merge-base --is-ancestor 6d327df master && echo landed   # use main if the repo has no master

The work has landed only if every reviewed commit is on the default branch. If some are and some are still on a branch, it has not landed: follow steps 4 and 5.

If nothing names the ticket, that is the finding. Do not review the working tree on the assumption that whatever is uncommitted must be the work, and do not report a pass you could not check. Comment what you searched for and stop: a ticket sitting in reviewing with no traceable work is exactly what a reviewer is for.

3. Judge each criterion separately

One criterion at a time, by its number from show, and each against the code. Never against the implementation plan: the plan is what someone meant to do, and a review that confirms the plan was followed cannot notice that following it was not enough.

Read the code the criterion is about, not only the lines the diff touched. A criterion that the diff satisfies and the surrounding code defeats is not met.

Give each one a verdict and its evidence, a file and a line:

  • met - and where.
  • not met - and what is missing.
  • cannot tell - and what would settle it. This is a real verdict. Use it instead of guessing, and say what you would have to run or read.

Run whatever the repo runs, its test suite and its linter. A suite that fails is not a criterion, but no criterion is met while it fails.

Then the two questions the criteria cannot ask themselves:

  • What did this change break that no criterion covers? Silent behaviour changes, a message or exit code something else reads, an edge case the ticket never named.
  • What did the ticket never think of? That is what you append in step 5, or file as a ticket in step 6.

4. Write one comment

If the work has landed, skip to step 6 now. It uses this comment's structure, but only after the new tickets exist, so their ids can go in it.

One call, one comment. Not one per criterion: the board renders comments in the order they were written, and a review split over eight of them cannot be read as a verdict.

worklane comment 1b78a24 "**Verdict**: two criteria unmet, the scroll clamp is off by the header

**Work reviewed**: 4edc7fa, 6d327df on feature/tui-scroll, not merged

**Criteria**
1. met - PageUp and PageDown reach detail_scroll, src/tui.rs:412
2. not met - the footer still lists the arrow keys, src/tui.rs:88
3. cannot tell - no test covers a ticket longer than the viewport

**Findings**
- The clamp uses the raw line count, so a wrapped ticket scrolls past its end, src/tui.rs:430
- Unticked criterion 2 accordingly

**Recommendation**: back to committed, the clamp is the ticket's own subject"

Keep the structure, drop the sections that have nothing in them. **Work reviewed** is never empty: it holds the shas, the branch, or what you searched for and did not find. Write for the person who has to act on it, so every finding says where it is.

The comment body takes a leading hyphen without being parsed as a flag, so a finding can quote --force literally. A body of exactly -- needs its own separator.

5. Write the verdict back to the ticket

worklane uncheck 1b78a24 2 5
worklane append 1b78a24 --acceptance "The footer lists only the keys that are bound"

Untick every criterion you found unmet, by the numbers show printed, in one call. Do it after the comment so there is a written reason on the board before the mark changes. Do not reach for all: a review unticks what it found unmet, and unticking the lot would erase the implementer's claim on the criteria you agreed with.

Never tick a criterion. A tick is the implementer's claim that something is done, and unticking is the review disagreeing with that claim. A reviewer that also ticks makes both the same mark, and the board stops recording that anyone ever disagreed. A criterion you found met but left unticked is a line in the comment, not a mark for you to fix.

Append a criterion only for work the next commit has to make true, phrased so it can be ticked off. Advice, praise and anything already covered by an existing criterion belong in the comment. An appended criterion that restates a finding just makes the ticket longer without making it clearer.

Do not move the ticket. mv belongs to whoever does the work, the same way ticking does. Your half is the recommendation in the comment; acting on it is theirs. A reviewer that reviews and closes in one breath leaves nobody to disagree with. This rule holds for work that has not landed; landed work follows step 6.

6. When the work is already on master

Use this step instead of steps 4 and 5 when step 2 found every reviewed commit on the default branch. Do not do steps 4 and 5 as well.

Landed work is not sent back to committed. That would reopen code that has shipped, and whatever fixes the findings is a new change anyway. So every remaining issue moves to a new ticket, and this ticket is closed.

An issue is any of these: a criterion you judged not met, a finding from the two questions in step 3, and a "cannot tell" whose answer needs work, such as a missing test. A "cannot tell" you settle by reading or running something is not an issue: settle it.

Do these in order, and do not skip ahead:

  1. File a ticket for every issue, the way the worklane skill says, searching the backlog first. Issues that are related, because they touch the same function or one fix would close them all, go into one ticket together. Unrelated issues get a ticket each. An issue that already has an open ticket gets a comment there, not a new one.

  2. Link each new ticket back to the one under review: worklane relate <new> --relates-to 1b78a24, or worklane relate <new> --regression-of 1b78a24 when the reviewed change broke something that used to work.

  3. Write the review comment, in the structure of step 4. List each issue under **Findings** with the id of the ticket that now holds it, and recommend done.

  4. Untick every unmet criterion with worklane uncheck, as in step 5, so the closed ticket does not claim what the code does not do. Do not append criteria: work for a later commit belongs to the ticket that commit will close, and nobody works a done ticket.

  5. Write a closing comment, separate from the review comment, immediately before the move. It says why the ticket is closing and names the ticket that holds each remaining issue:

    worklane comment 1b78a24 "Moving to done: the work is on master, and every remaining issue has its own ticket: 7bfb9fc (wrapped-line clamp), 4179958 (footer keys)"
    

    With no issues at all, steps 1, 2 and 4 have nothing to do, and the closing comment says that: Moving to done: the work is on master and the review found no remaining issues. The review comment is the verdict; the closing comment is the reason for the status change, and it sits in the history right above the move. Without it, a done ticket with unticked criteria looks closed by mistake.

  6. Move it to done: worklane mv 1b78a24 --status done. This is the only move a reviewer makes. Make it last: an issue without a ticket is lost once this one is done. With every issue in its own ticket, nothing is left here for the implementer, and leaving the ticket in reviewing only hides that the review is finished.

What a reviewer does not touch

  • The description, plan, title, priority and tags. Rewriting the ticket you are reviewing destroys the record of what was asked for, which is the only thing your verdict can be measured against. Say it in the comment.
  • The code. Even a one-line fix is a finding: whoever wrote it gets to make the change, and gets to keep the review that asked for it. Fix it only if you are asked to, and then it is a new piece of work with its own comment.
  • Another ticket's business. Something you found that is genuinely out of scope gets its own ticket, filed the way the worklane skill says, and worklane relate <new> --relates-to <this> so the two are findable from each other.

Reviewing what is waiting

worklane ls reviewing

One ticket at a time, with its own comment. A single comment covering four tickets lands on one of them and is lost to the other three.