--- name: worklane-review description: 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, and what a reviewer may and may not write back to the board. --- # 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 Three things, in this order, and nothing else: 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. 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. ## 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 is not done, or a `regression of`, changes what the change was allowed to do and what the review has to check twice. ## 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. **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. ## 4. Write one comment 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 master **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. ## 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 --relates-to ` 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.