Finishing a ticket means ticking every box, and that was one invocation per box: each one resolved the ticket, spliced one line and rewrote the file. The criterion positional is now variadic, so numbers and substrings mix in a single call, and `all` stands for every criterion on the ticket. `all` is a keyword checked before the text, the way the index already is, so a criterion whose own words include "all" is reached by its number or by a longer substring. `is_all_criteria` sits beside `is_index` for that reason. `resolve_criteria` resolves every term before a byte is written and refuses the whole batch on the first term it cannot place, naming it. A call that ticked what it understood and then failed would leave the ticket half-marked with nothing in the file to say which half was meant. The offsets are sorted and deduped, so the report reads in `show`'s order and a criterion named twice, or by both `all` and its number, is marked once. `set_criterion` becomes `set_criteria` and takes every line in one pass. Each named criterion gets a line, printed after the write. One already in the target state reads `Already checked 2: text` and does not count towards the write, so a batch where every box is already ticked writes nothing. The opencode wrapper takes the terms one per line, like the other list arguments. REVIEW.md gains the one thing a reviewer must not do with this: reach for `all`, which would erase the implementer's claim on the criteria the review agreed with. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
163 lines
7.6 KiB
Markdown
163 lines
7.6 KiB
Markdown
---
|
|
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 <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.
|