diff --git a/skills/steward/SKILL.md b/skills/steward/SKILL.md index e71b7ef..c681cc2 100644 --- a/skills/steward/SKILL.md +++ b/skills/steward/SKILL.md @@ -152,7 +152,7 @@ A seat that muster has just handed the effort to breaks it too, because it may h The beads in delivery are the `delivery` lines of step 4, each with its pull request and its gate. Under a delivery formula, the line names the work bead that waits on its molecule's outcome step. Then close the berths you started that are no longer on open work, as *Watching the berths you started* says. A berth whose bead no longer names it appears in none of the lists above. -7. **Match your watches to the effort's waits.** Every open question bead a sleeping worker depends on, every foreign dependency that holds a bead in push-gate state 6, and every bead in delivery gets a beady-eye `watch`. The bead in delivery to watch is the work bead: under a delivery formula, the bead that waits on the outcome step, and otherwise the bead behind its own `gh:pr` gate. It goes ready once that step or gate closes. Name the project for a foreign bead. Compare beady-eye's `watching` list against those waits. Watch what is missing, which after a fresh start is all of them, and `unwatch` what no longer holds anything up. +7. **Match your watches to the effort's waits.** Every open question bead a sleeping worker depends on, every foreign dependency that holds a bead in push-gate state 6, and every bead in delivery gets a beady-eye `watch`. The bead in delivery to watch is the work bead: under a delivery formula, the bead that waits on the outcome step, and otherwise the bead behind its own `gh:pr` gate. It goes ready once that step or gate closes. Where a gate sweep runs, as *Watching your pull requests* says, also watch every bead that an open `gh:pr` gate of the effort directly blocks, because the sweep comments there. Without a formula that is the work bead again. Under one it can be a later step of the molecule. `bd dep list --direction up --type blocks` lists them. Name the project for a foreign bead. Compare beady-eye's `watching` list against those waits. Watch what is missing, which after a fresh start is all of them, and `unwatch` what no longer holds anything up. 8. **Read the topics.** Read the decisions topic and each active worker's working topic: who is mid-flight, who is blocked, and what has been asked of the human. After a compaction you are still subscribed to every topic an earlier you created. The only subscription you might still owe is to a topic someone else created. You are now bound, reachable, and hold the whole state. Reconstruct from these reads, never from memory. @@ -190,9 +190,9 @@ You bloat, and force expensive compaction, by pulling detail of the work into yo **A wait for a date goes on its bead, not only in a wake.** A `ScheduleWakeup` dies with your session, so defer the bead to the date as push-gate state 7 says. You may also schedule a wake for the date. If your session has gone by then, the bead shows as ready and tally shows the effort with no live steward, and a person starts one. - **A bead you wait on wakes you through your watch on it.** A closed question bead or foreign dependency ends a wait, so `unwatch` it and run the wake ritual. A comment, or any change that leaves the bead open, is nothing to act on unless it is a question for you. + **A bead you wait on wakes you through your watch on it.** A closed question bead or foreign dependency ends a wait, so `unwatch` it and run the wake ritual. A comment, or any change that leaves the bead open, is nothing to act on unless it is a question for you, or a gate sweep's report of a pull-request event. - **A merge wakes you through your watch on the bead in delivery.** Once the pull request merges and its gate closes, the bead goes ready, and the watch says so. A watch cannot see a pull request that needs work, such as one with changes requested, a failing check or a needed rebase. So also schedule a poll of your pull requests, on the timescale a review really takes, hours rather than minutes. + **A merge wakes you through your watch on the bead in delivery.** Once the pull request merges and its gate closes, the bead goes ready, and the watch says so. A watch sees a pull request that needs work, such as one with changes requested, a failing check or a needed rebase, only where a gate sweep comments it onto a watched bead, as *Watching your pull requests* says. Where no sweep runs, also schedule a poll of your pull requests, on the timescale a review really takes, hours rather than minutes. **While beady-eye says its watcher is down, your watches wake no one.** Until it says the watcher is answering again, poll the beads you watch within the hour, because workers sleep on them, and when a question bead closes, post its answer, quoted from the bead, into its worker's working topic. - **You act; you don't report.** The wake ritual's output is for you. Never narrate your orientation or your plan into the terminal, where it reaches no one. What you emit is actions: a brief, an ask, a bead update. @@ -459,7 +459,11 @@ Judge liveness by work product, meaning recent posts, commits and bead updates, ## Watching your pull requests -An open pull request is a live strand with no seat on it, so nothing moves it unless you do. Your watch on its bead wakes you once it merges and its gate closes, as *Reconstruct* step 7 says. A watch sees nothing of a review, so your scheduled poll finds a pull request that needs rework, and finds a merge while beady-eye says its watcher is down. At each wake, run `bd gate check --type=gh:pr` to close the gate of every merged pull request. The beads behind those gates go ready, and *Reconstruct* closes them. Then walk your own beads in delivery, reading each pull request from its gate, and ask about each one by number: +An open pull request is a live strand with no seat on it, so nothing moves it unless you do. Your watch on its bead wakes you once it merges and its gate closes, as *Reconstruct* step 7 says. + +**A gate sweep turns a pull request's events into comments on beads.** Some hosts run one on a schedule. It settles each open `gh:pr` gate whose pull request has merged, and comments each review, each conversation comment, each failing check and each merge conflict onto every bead that gate directly blocks, naming the author on the forge. Your host's instructions say whether one runs. Where it does, your watches on those beads deliver each event, so let them wake you rather than scheduling a poll of your pull requests. A comment from the sweep wakes you: walk the pull request it names, as below, and act on what you see. Where no sweep runs, a watch sees nothing of a review, so your scheduled poll finds a pull request that needs rework. + +While beady-eye says its watcher is down, a poll also finds a merge. At each wake, run `bd gate check --type=gh:pr` to close the gate of every merged pull request. The beads behind those gates go ready, and *Reconstruct* closes them. Then walk your own beads in delivery, reading each pull request from its gate, and ask about each one by number: ```bash gh pr view "$N" -R "$OWNER/$REPO" \ @@ -474,7 +478,7 @@ Then act on `state` first: |---|---| | `OPEN`, a draft, or not a draft with no `reviewDecision` | Nothing. It waits on the human's review or merge, and its gate is the one record of that. | | `OPEN`, not a draft, every check green, **and the repo's declared policy says its agents merge on green** | Merge it with `gh pr merge -R "$OWNER/$REPO" --squash --delete-branch`, then act on the `MERGED` row in the same pass. Without that policy this row does not exist, and the merge is the human's. | -| `OPEN`, `reviewDecision: CHANGES_REQUESTED`, or a failing check | Start a rework seat on the same bead, with the review comments in the brief. | +| `OPEN`, `reviewDecision: CHANGES_REQUESTED`, a failing check, or a comment that asks for a change | Start a rework seat on the same bead, with the review comments in the brief. | | `OPEN`, `mergeStateStatus: BEHIND` or `DIRTY` | Start a rework seat on the same bead to rebase. | | `MERGED` | Close its gate with `bd gate resolve `, close the bead, fast-forward the main checkout as *Advancing the chain* says, then sort the graph again as *Reconstruct* step 4 says. | | `CLOSED` | Nobody will merge it, and its gate stays open. File a question bead, asking whether to reopen it, redo it, or drop the bead. A bead in delivery on a dead pull request blocks its dependents for ever. Once the human answers, close the gate with `bd gate resolve `, unless they reopen the pull request. |