install-skill now writes every document the binary carries, with an optional name to narrow it. Requiring a name per document would mean a skill added later never reaches anyone who already knows the invocation, which is the drift the command exists to prevent. --print is the exception and requires the name: a diff is against one document. The review skill is its own document rather than a section of SKILL.md, because the frontmatter description is the whole of what decides loading and one description cannot name both "anything touching a ticket" and "only when a review is asked for". The reviewer never ticks a criterion and never moves the ticket. A tick is the implementer's claim and unticking is the review disagreeing; one mark for both loses the disagreement. mv belongs to whoever does the work. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
7.5 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, 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:
- One comment on the ticket, in the structure below.
- Unticked criteria, for the ones the code does not actually meet.
- 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
worklane append 1b78a24 --acceptance "The footer lists only the keys that are bound"
Untick every criterion you found unmet, one call each, by the number show printed. Do
it after the comment so there is a written reason on the board before the mark changes.
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
worklaneskill says, andworklane 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.