diff --git a/website/docs/apps/board.mdx b/website/docs/apps/board.mdx index 93b310f463..3cee411431 100644 --- a/website/docs/apps/board.mdx +++ b/website/docs/apps/board.mdx @@ -28,6 +28,8 @@ Open board from the mattstack window, or at `https://board.mattstack`. It is a t **Run reviews through Slack.** board follows a channel convention: a review request is a message with the MR link, and review state is signalled with three reactions (looking, commented, approved). You can post a request and [set the reactions](#slack-reactions) from a row. +**Read and answer review comments.** The row's thread count opens [the comments drawer](#comments-and-threads), where you can reply to a thread and resolve it without leaving the board. + **Ask a teammate's agent.** When teammates run their own boards, your board can ask their agents to work on your MRs, and theirs can ask yours. [Asks between boards](#asks-between-boards) follows an ask from start to finish. ## Three things decide what you see @@ -279,6 +281,23 @@ An MR that is already where an action would take it, such as already rebased, is The board runs the action on four MRs at a time, then shows one summary, for example "merge accepted on !1, !2 · couldn't merge !3 (not approved yet) · 1 didn't need it". +## Comments and threads + +A row with review comments shows a count, such as "3 threads". It counts review threads and MR comments together. It reads "2 threads waiting" when threads wait on you, and "author replied" when the author answered yours. Click it to open the comments drawer for that MR. + +The drawer lists the MR's review threads, each with its status: **awaiting author**, **author replied** or **resolved**. Below them, **MR comments** holds the Overview comments that are not threads. Each comment links to its place in GitLab. + +The drawer and the count leave out what is not feedback: MR comments from bots, automatic links among MR comments, threads where only the author and bots took part, and the thread the board itself adds to ask for a follow-up review. + +On a local board you can also write from the drawer: + +- **reply** opens a reply box under a thread. Press ⌘↩ or **send** to post it, or Esc to close the box. +- **send & resolve** posts the reply and resolves the thread in one step. +- **resolve** and **unresolve** work on every thread of your own MR, and on threads you started on someone else's. +- An MR comment takes a reply once someone other than the author has commented. It cannot be resolved. + +The drawer sends one write at a time. When a write fails, its error shows under that thread, for example "reply sent, but resolve failed". + ## Decisions waiting on you When an agent waits on a decision of yours, a banner above the header says so, for example "3 decisions are waiting on you". It names the MR it starts with and how long that decision has waited. **Open queue** opens the decisions one after another, in the order the board lists their MRs. A response or doctor decision on someone else's MR opens read-only, since only the MR's author can answer it. diff --git a/website/docs/skills/index.mdx b/website/docs/skills/index.mdx index 7407053be7..655046cd76 100644 --- a/website/docs/skills/index.mdx +++ b/website/docs/skills/index.mdx @@ -45,3 +45,4 @@ If you maintain a team pack, [`rt skills sync`](/rt/reference/skills/sync) bring - [MCP server](/skills/mcp): the tools agents call instead of shell commands. - [herdr-chat](/skills/herdr-chat): chat controls inside herdr panes. - [gitq skills](/skills/gitq-skills): the Claude skills that drive gitq. +- [Review rule selector](/skills/rule-selector): review only the team rules a change touches. diff --git a/website/docs/skills/rule-selector.mdx b/website/docs/skills/rule-selector.mdx new file mode 100644 index 0000000000..9bc825addb --- /dev/null +++ b/website/docs/skills/rule-selector.mdx @@ -0,0 +1,83 @@ +--- +sidebar_position: 11 +title: Review rule selector +--- + +# Review rule selector + +A pack can give its reviews a rule selector: a command that reads a change's diff and picks only the team's review rules that apply to it. The reviewer then gives a verdict on each picked rule, and every rule it fails becomes a finding. Without a selector, the review engines work as they always have. + +The selector is for teams that keep their review rules as files a tool can match against a diff. mattstack ships no selector; your pack's fill names the commands. + +## Where it runs + +| Verb | What the selector does there | +| --- | --- | +| `review` and `self-review` | Picks the rules before the reviewer starts, asks for a verdict on each, checks the verdicts, and turns each failed rule into a finding | +| `receive-review` | Picks the rules for the branch and hands them to the agent judging the review threads, as reference only | +| The implement stage | Runs the optional `check:` command once, then fixes the rules the change breaks before committing | + +## Bind a selector + +Write a fill skill whose text resolves to the selector's command lines, then bind it to the `rule-selector` prop of each verb's `rule-selector` block: + +```bash +rt skills bind review review/rule-selector rule-selector widgets:rule-selector --pack widgets +rt skills bind self-review self-review/rule-selector rule-selector widgets:rule-selector --pack widgets +rt skills bind receive-review receive-review/rule-selector rule-selector widgets:rule-selector --pack widgets +rt skills bind stage-implement stage-implement/rule-selector rule-selector widgets:rule-selector --pack widgets +``` + +Publish the pack the way every pack change goes out, through `mattstack:extending-a-pack` and `mattstack:editing-skills`. + +## What the fill says + +The agent reads the fill on every run, so it can look at a setting first. It resolves to one of two shapes. + +To turn the rules off for this run: + +```text +selector: none +``` + +To run them: + +```text +selector: widgets-rules select --format {format} +verdicts: widgets-rules check-verdicts {selection} {verdicts} +fence: widgets-verdicts +``` + +- **`selector:`** runs twice with the diff on stdin: once with `{format}` as `json`, to get the picked rules, and once as `text`, the Markdown the reviewer reads. The JSON needs a `rules` list, and each rule has an `id`, a `severity` (`blocking` or `advisory`) and a `summary`. +- **`verdicts:`** checks the reviewer's answers. `{selection}` and `{verdicts}` are file paths. It prints `{"problems": [...]}`, exiting 0 with no problems and 1 with some. +- **`fence:`** is the tag of the code block the reviewer writes its verdicts in. +- **`check:`** is an optional fourth line for the implement stage. It runs in the worktree, with `{base}` replaced by the branch point, and prints the rules that apply and the lines worth a look. + +## What the reviewer returns + +The reviewer ends its reply with one code block, tagged with the `fence` value: + +```json +{"verdicts": [{"rule": "no-raw-sql", "verdict": "fail", "evidence": [{"file": "src/orders.ts", "line": 12, "side": "new"}], "note": "builds the query by hand"}]} +``` + +Each `verdict` is `pass`, `fail` or `not-applicable`. + +## How verdicts become findings + +- A `blocking` rule that fails becomes an Important finding, and an `advisory` rule a Minor one. Only the reviewer marks something Critical. +- A finding sits at the rule's first new-side line. When the reviewer already reported the same problem at that line, the two become one finding. +- When the verdicts command finds problems, a fresh reviewer corrects the verdicts once. Problems left after that go into the draft's notes, and the review carries on. +- The verdicts are saved as `review-verdicts.json` in the review's scratch folder. + +A selector that fails, or prints JSON the review can't read, never blocks a review. The review notes it as a setup problem and goes on without rules. + +## Turn it on for a team + +`review.ruleSelector` is the switch a fill can read. It is off by default, and a team, a user or a machine can turn it on: + +```bash +rt settings set review.ruleSelector true --scope team +``` + +A fill that reads it resolves to `selector: none` while it is off.