diff --git a/Cargo.lock b/Cargo.lock index 056a8fc..b2169aa 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1563,7 +1563,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.33.9" +version = "0.33.10" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index ddf0a22..aaa68dc 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.33.9" +version = "0.33.10" edition = "2024" [dependencies] diff --git a/assets/REVIEW.md b/assets/REVIEW.md index 9db382e..232e1e3 100644 --- a/assets/REVIEW.md +++ b/assets/REVIEW.md @@ -1,6 +1,6 @@ --- 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. +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, 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 @@ -14,14 +14,21 @@ addressed and the argument traps, is the `worklane` skill; read that too. ## What a review produces -Three things, in this order, and nothing else: +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. -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. +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 @@ -59,6 +66,16 @@ 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 @@ -87,17 +104,21 @@ 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. +- **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 master +**Work reviewed**: 4edc7fa, 6d327df on feature/tui-scroll, not merged **Criteria** 1. met - PageUp and PageDown reach detail_scroll, src/tui.rs:412 @@ -142,7 +163,54 @@ 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. +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 --relates-to 1b78a24`, or `worklane relate + --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 diff --git a/docs/agent-assets.md b/docs/agent-assets.md index 135402d..50473a9 100644 --- a/docs/agent-assets.md +++ b/docs/agent-assets.md @@ -16,7 +16,7 @@ The documents and the opencode tool file the binary carries, and how they are in - The refusal message names the document it is about, `install-skill worklane --print`, since with several installed "compare with --print" does not say compare what - **A refused document does not stop the ones behind it.** The loop reports an outcome per document and the "pick it up on their next session" line is printed once, and only when something was actually written - **A role skill is its own document, not a section of `SKILL.md`.** The frontmatter description is the whole of what decides whether a skill loads, and one description cannot name both "anything touching a ticket" and "only when a review is asked for" without fitting neither. It is also why the review document does not restate the CLI: it says to read the `worklane` skill too -- The review skill's own rules are guarded by `the_review_skill_keeps_the_decisions_that_define_it`, because each of them is a line an edit could drop without breaking anything: **the reviewer never ticks a criterion** (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), **never moves the ticket** (`mv` belongs to whoever does the work, the reviewer's half is the recommendation), and **never reviews the working tree when no commit names the ticket** (it says what it searched for and stops, since an untraceable ticket in `reviewing` is itself the finding) +- The review skill's own rules are guarded by `the_review_skill_keeps_the_decisions_that_define_it`, because each of them is a line an edit could drop without breaking anything: **the reviewer never ticks a criterion** (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), **never moves the ticket** (`mv` belongs to whoever does the work, the reviewer's half is the recommendation) **unless the work is already on master** (then each finding gets its own ticket, related ones sharing one, and the reviewer moves the original to done once all of them are filed, after a comment saying which ticket holds each remaining issue, since a done ticket with unticked criteria otherwise reads as closed by mistake: sending landed work back to committed reopens shipped code, and leaving it in reviewing with nothing left to do only hides that the review is over), and **never reviews the working tree when no commit names the ticket** (it says what it searched for and stops, since an untraceable ticket in `reviewing` is itself the finding) - **The plan skill is the one that can do damage, so its rules are the ones under test.** `set --tags` replaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable. `the_plan_skill_keeps_the_rules_that_bound_a_sweep` pins propose-then-apply and those two traps, because a document that loses them still reads like a plan - `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document - **`install-tool` is a second command, not a flag on `install-skill`, because the two artifacts are not alike.** A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: `claude mcp add` with a `stdio`, `sse` or `http` transport is the only way a tool enters its tool list, and its plugin system adopts `agents`, `hooks`, `monitors`, `workflows`, `output-styles` and `themes` and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238 diff --git a/src/install.rs b/src/install.rs index 318c3b1..94621cc 100644 --- a/src/install.rs +++ b/src/install.rs @@ -526,6 +526,9 @@ mod tests { "nothing names the ticket", // and the no-work-found case is answered "Never tick a criterion", "Do not move the ticket", + "already on master", // landed work: findings become tickets, then done + "File a ticket for every issue", + "Write a closing comment", // and says so before the move "worklane uncheck", "worklane append", "cannot tell",