work

Files (1)

• SKILL.md

SKILL.md (first lines)

# Work: what needs doing, and who does it

These are the ways to say that a bead needs work, who should do it, or that it
needs none. Each option says what the message means, who acts on it, and the
one writer that sends it. The writer's `--help` carries its flags. Doing the
work is a molecule's job, so nothing here changes a repo.

The writers are the gc-toolkit pack's own scripts.
`gc <binding> scripts-dir` prints their directory in the pack as gc loaded it,
so each example calls the pack's copy inside the command itself, and runs in a
fresh shell. `<binding>` is the name the city imports the pack under, which gc
puts in front of this skill's name: `gc-toolkit` in `gc-toolkit.work`.
`gc skill list` prints it in this skill's FROM column.

## File new work

A new bead says that work needs doing. Filing it starts nothing: send it, make
it wait, or leave it for placement.

- **A dependency goes beside the bead it came from, never under it.** Work
  that bead waits on is a dependency, and this is the default. bd refuses a
  `blocks` edge from a parent to its own descendant, so a child could never
  gate the bead it came from. Work already filed under the bead it came from
  stays where it is.
- **Work that genuinely decomposes an epic is a member of that epic.** A story
  or task that is part of the epic's work is filed with `--parent <that epic>`,
  even when the epic is the bead it came from. Nothing makes the epic wait on
  it with a `blocks` edge, because containment already carries that wait.
- **Give it a parent only when one applies.** A parent makes the bead a member
  of that epic: a park on the epic holds it, and the epic's priority ranks it.
  The parent of the bead it came from applies only when the new work serves the
  same epic. This prints that parent, or an empty line:
  `"$(gc <binding> scripts-dir)/converse-parent.sh" <bead>`. When no epic
  applies, give the bead no parent.
- **File it in the store of the pool that will work it.** A pool reads only its
  own rig's store, so a city-scoped session names the rig:
  `gc bd --rig <rig> create`.
- **Send it now when intake admits it, and hold only the rest.** Epics are how
  the operator steers which work runs, and membership is one of four ways in
  (`docs/steering.md`). A bead goes to a pool now when it is a member of an
  epic, when it is PR-finishing work carrying `anchor_bead`, when it is an
  emergency, or when the operator routed it in a sitting, by hand or by Accept.
  An emergency is a red main or a broken gate, confirmed by a check that failed
  on the default branch's head. Critical work the operator wants run now goes
  through the operator's own routing. Any other bead carries
  `placement=pending` in its create and no route or arm, and the operator's
  placement sitting places it.

Writer:

```bash
gc bd create "<title>" -t task -d "<what needs doing, why, and what done looks like>" --json
```

Add `--parent <epic>` when an epic applies, and
`--metadata '{"placement":"pending"}'` when intake holds the bead. The
description is the contract the worker reads.

## Send a bead to a pool on a formula

The message is that this pool does this work by this method. The pool's
workers claim the workflow the sling pours, and the formula's steps are their
plan.

Writer: `gc sling <rig>/<pool> <bead> --on <formula>`. With no `--on` it pours
the target's `default_sling_formula`, which for a polecat pool is
`mol-polecat-work`.

- **One dispatch, never two.** A sling pours a workflow and stamps
  `gc.execution_routed_to` on the bead. A raw route, `gc.routed_to=<pool>`,
  which a sitting's sign-off `--route <pool>` also writes when it releases a
  held subject, has the pool claim the bead itself. Send it one way. Both start
  two workers on one branch.
- **Release its wait first.** A worker's first step builds nothing that still
  waits. It re-arms a bead with an open blocker to be sent again when the
  blocker closes, and it ends the run on a bead that carries a `merge_result`,
  `held` included, as finished. Release the wait (the waits skill), then send.
- **A named agent takes an assignee.** The mechanik, deacon, witness,
  refinery and keeper are named agents, and the assignee is what the
  controller and the pack's notice read to give one a turn
  (docs/deferred-dispatch.md). Send one of them a bead with
  `gc bd update <bead> --assignee <qualified-name>`, the name `gc agent list`
  prints, then tell it with
  `"$(gc <binding> scripts-dir)/deferred-dispatch.sh" notify <bead> --agent <qualified-name>`.

In a sitting, the sign-off's `--route` says where the subject itself goes once
its wait is released (the converse-settle step), so first decide which bead
carries the work:

- **The subject is the work.** Sign off with `--ruled yes --route human --no-wait`,
  then send the subject: `gc sling <rig>/<pool> <subject> --on <formula>`. The
  sling clears that human route. `--route <rig>/<pool>` would route the
  subject raw as well, a second dispatch.
- **New work carries it, and the subject waits for it.** File the work, send
  it, and sign off with `--ruled yes --route human --waiting-on <the work>`.
  The board shows the subject as a ruling in flight until the work lands, then
  as settled. A `--route <rig>/<pool>` here would have that pool claim the
  subject itself once the work lands, a conversation seed no worker can close.
- **New work decomposes an epic subject.** It is the subject's member: file it
  with `--parent <subject>`, send it, and sign off with
  `--ruled yes --route human --no-wait`. `--waiting-on` names a dependency
  only, because bd refuses a `blocks` edge from a parent to its own
  descendant, and containment already carries the wait. When the sitting also
  sent a dependency, name that one with `--waiting-on` in place of `--no-wait`.

## Take a recommendation

A first reaction that cannot route a bead itself records the formula it
recommends as `gc.recommended_formula`, and the operator decides. Take it only
on the operator's go. The pool on that formula acts.

Release the wait that put it to the operator (in a sitting, the sign-off for a
subject that is the work, above), send it on that formula, then record the
dispatch in one update, which runs only once the sling succeeded:

```bash
gc sling <rig>/<pool> <bead> --on <the recommended formula> \
  && gc bd update <bead> --set-metadata gc.recommended_formula_dispatched=<the formula> --unset-metadata gc.recommended_formula
```

From zookanalytics/gc-toolkit, MIT.

More from zookanalytics/gc-toolkit