chamba 0.6.1 → 0.8.0

package/templates/skills/dx-review/references/acts.md

@@ -0,0 +1,162 @@
+# The three acts, in detail
+
+Read the act you are doing.
+`SKILL.md` says how you learn which one that is: `reviews state "<review>"`, and then `awaits.act`.
+
+Everything here is posted with the verbs of `SKILL.md`, and nothing else writes to a review.
+
+## prepare - the review has a baseline and no grouping
+
+The reviewer has filed a review and is waiting to read it.
+Until you post a grouping the screen shows every hunk under "Not grouped yet", which is a wall of diff with no story in it.
+So this act is the one the reviewer waits on longest, and it is the one that decides how the review reads.
+
+**1. Read the change before you group it.**
+The state's `baseline` holds every file and, for each one, the id and header of each of its hunks.
+Read the code itself as well - the files of the workspace are there, and the review is of the tree you are in.
+A grouping written from headers alone groups by file, which the tab could have done without you.
+
+**2. Group by intent, not by file.**
+A group is a piece of work somebody did: "the discount rules", "the new error path", "the rename that follows from it".
+Three to seven groups reads well for most changesets.
+One group of forty hunks says nothing, and twenty groups of two are the file list again.
+
+- A hunk may sit in several groups where it belongs to both.
+- A hunk in no group lands under "Ungrouped", which is the tool's own group. It is for the case where you missed one, and a review that shows it is a review you left half grouped.
+- `ungrouped` in the post's answer is that list. Read it, and post again with the hunks it names in the groups they belong to.
+
+**3. Give each group a narrative and its facts.**
+The narrative is a short paragraph in plain language: what this piece of work does, and why the change is what it is.
+The reviewer reads it before the hunks, so it says the thing the diff cannot - the intent.
+The facts are a few short lines of what is true and checkable: "adds one table column", "no call site outside the cart", "the old path stays for one release".
+Facts are facts. Anything that needs "I think" is not one.
+
+**4. Write the notes.**
+You read every line of this change, and the reviewer has not.
+The notes are what you learned while you read, beside the code, so that the human review is quick and misses nothing.
+A note is plain text of one kind, on one hunk or on a line range inside it.
+
+- `info` - an explanation that helps the reviewer understand the code: what a passage does, why the change is the way it is, what it mirrors elsewhere. "This mirrors the rule in `pricing.ts`." Write one wherever an explanation would save the reviewer a search or a guess.
+- `attention` - anything that deserves the reviewer's eyes, whether or not you found a fault in it: a hard passage, a change of behaviour, a decision with a trade-off, a place you believe is right and a human should confirm. "This drops the guard the caller used to hold." Attention is relative to this changeset: it marks the parts of this change that most need a human.
+- `issue` - something you are certain is wrong. The text says what is wrong in one or two sentences and, where you see it, how to fix it. "The loop never steps `i`, so it never ends. Step it at the end of the body." Write an issue only when you are sure; where you are not, write `attention` and say what you suspect.
+
+The screen counts the open `issue` and `attention` notes on each group and in the status bar, so the reviewer sees where the eyes are needed before they read.
+The reviewer can dismiss a note, ask you to fix an issue, or open a conversation on it.
+One note per thing you have to say, and the kind that fits it.
+A note on every hunk is a rail nobody reads, but a hunk that needs an explanation and has none is a question the reviewer has to ask you.
+
+**Do not fix anything in this act.**
+You found the issue, and the reviewer decides what to do with it: the fix is an item in the batch they send, and `process` is where you do it.
+
+**5. Post it.**
+
+```
+echo '{
+  "fingerprint": "sha256:...",
+  "groups": [
+    { "id": "discount-rules", "name": "Discount rules",
+      "narrative": "The rules move out of the cart and into one place ...",
+      "facts": ["adds one table column", "no call site outside the cart"],
+      "hunks": ["src/cart/discount.ts#9f3a...#1", "src/cart/discount.ts#9f3a...#2"] }
+  ],
+  "notes": [
+    { "hunk": "src/cart/discount.ts#9f3a...#1", "kind": "attention", "lines": [44, 46],
+      "text": "This drops the guard the caller used to hold." },
+    { "hunk": "src/cart/discount.ts#9f3a...#2", "kind": "issue", "lines": [61],
+      "text": "The loop never steps `i`, so it never ends. Step it at the end of the body." }
+  ]
+}' | reviews metadata "<review>"
+```
+
+`fingerprint` is the baseline's own, from the state you read.
+`id` is yours to choose and is the name the tool refers to the group by; `name` is what the reviewer reads.
+`kind` is `info`, `attention` or `issue`.
+`lines` are new-side line numbers inside the hunk, and a note without them is about the whole hunk.
+The screen draws one bar in the gutter from the smallest number to the largest, so two numbers name a range.
+
+**A post replaces the whole grouping.**
+That is what makes a group appear as it becomes ready: post the groups you have, and post them all again with the next one added.
+The screen then shows three groups, then four.
+A post with no group empties the grouping, which is what it says.
+
+**6. Say what you are doing, and finish.**
+Post `activity` as you work through it - "Grouping the parser changes, 3 of 5 ready" - and `done` when the grouping is complete and every note is in.
+
+**Say how many groups there will be, in `groups`.**
+
+```
+echo '{ "said": "Grouping the parser changes, 3 of 5 ready", "groups": 5 }' | reviews activity "<review>"
+```
+
+You are the only one who knows it: the tool holds the groups you posted, and the tab draws one card waiting for each group you promised and has not arrived, so the reviewer sees how much is still coming.
+Post it once you know the number, and post the sentence alone after that - the count stands until you post another, and it is cleared when the review goes back to the reviewer.
+
+## process - the reviewer sent a batch
+
+`send` in the state is the newest batch: when it was sent, the baseline it was written against, and its `items`.
+Each item is one thing the reviewer asked, and each one has already opened or joined a conversation on the hunk or the group it is about.
+
+An item carries:
+
+- `hunk` - the hunk it is about, or null for a comment on a group.
+- `group` - the group it is about, and null for everything else.
+- `act` - what the reviewer asked for: `undo` (undo the change), `explain` (explain it in a comment), `comment`, `fix` (fix what a note of yours says), or `group-comment`.
+- `lines` - the new-side lines the item is about, or null for the whole hunk or a group.
+- `text` - what they said, and it may be empty for an `undo` that speaks for itself.
+
+**Do the work first, and reply about what you did.**
+The order matters: a reply is a statement about the code, and a reply written before the change is a promise.
+
+- `undo` - put that hunk's change back as it was, unless doing so breaks something the reviewer cannot see. Where it does, do not undo it quietly: say what breaks, in the conversation, and leave the code as it is.
+- `explain` - the reviewer wants the reasoning, not a change. Answer in the conversation and change nothing.
+- `fix` - the reviewer read an `issue` note of yours and asks for the fix. The text is the note, with anything they added, and `lines` says where. Fix it, and reply with what you did.
+- `comment` and `group-comment` - read what they asked for and do it. It may be a change, a question, or both.
+
+**Reply in the conversation each item is on.**
+
+```
+echo '{ "thread": "<the thread id from the state>", "text": "Undone. The old guard is back, and ..." }' | reviews reply "<review>"
+```
+
+The `threads` in the state hold the id, the anchor and every message, so the thread of an item is the one whose anchor is that item's hunk or group.
+One reply per item, and each one lands live on the reviewer's screen under the hunk they were looking at.
+
+You cannot close a conversation, and you should not try to write a reply that reads like a closing.
+The reviewer closes a conversation when they are satisfied, and that is the whole point of the control.
+
+**Where an item is unclear, ask in the terminal.**
+Then do the item, and reply once you know what it asked.
+Do not reply with a question: a reply is your answer, and the tab draws it as one.
+
+**Finish with `done`.**
+It hands the review back and the tool recomputes the baseline, so the reviewer sees your commits as part of the review and every hunk they had read that you did not touch is still read.
+
+## sync - the baseline moved
+
+The reviewer synced the review, stopped you mid-act, or followed a merge.
+Either way the baseline is a new one, and the state's `metadata` is what you posted for the baseline before it.
+
+**What is already true, and what you do not have to do again.**
+The tool carried every mark, conversation and pending item onto the hunks that did not change, and it kept the grouping of every hunk that is still there.
+A hunk the reviewer had read whose content changed comes back unread with a "changed since you saw it" marker, which is the tool's, not a note of yours.
+
+So this act is the difference, and not the review again:
+
+1. **Group what is new.** `ungrouped` names the hunks no group holds. Most of them are new hunks, and each one belongs in a group that exists or in one more group.
+2. **Revise what the new code made wrong.** A narrative that describes code that is no longer there is worse than none, because the reviewer reads it as current. Read your own narratives against the new baseline and rewrite the ones that moved.
+3. **Read your notes again.** The tool dropped the notes of every hunk whose content changed, and kept the rest. Write again only the notes that are still true of the new code, and write notes for what is new. An issue you fixed gets no note: the rail shows the code as it is, not what it was.
+4. **Answer what is open.** A conversation the reviewer is waiting on is one that is open and whose last message is theirs. Answer it if the new code answers it.
+
+Post the whole grouping again, with the new baseline's `fingerprint`, and `done` when it is in.
+
+## The no-act case
+
+`awaits.act` is null, so none of the three applies.
+It happens two ways, and both are ordinary.
+
+- **`side` is `you`.** The review is with the reviewer. It came back to them when the last act posted `done`, or they stopped you and are reading it now. The command arrived because they asked again, or because it was typed by hand.
+- **`side` is `agent` and `act` is null.** The review is yours and names no act, which is a review that has nothing pending in it.
+
+Say so in the terminal, in one line, and post nothing.
+Not `activity`, and not `done`: `done` recomputes the baseline and hands back a review that was never taken, and the reviewer reads that as work that happened.
+Where the review is the reviewer's, every verb that writes is refused in any case, and the refusal is the right answer rather than something to work around.