Hold a Ritual

Hold a Ritual

A ritual is a recurring review, such as a retrospective, a dependency audit, a security review or a drill. It is held on a cadence and leaves durable output. Every run is one ritual-run issue, and each finding is linked to its own issue. This page walks one run from “is anything due?” to a closed run. The cadences, kits and the run issue’s format are in the Rituals reference.

Terminal only. These commands read and write issues on the project’s forge.

1. See what is due

bob ritual due --project <project>     # one project
bob ritual due --all                   # every active project manifest

Each row is OVERDUE, DUE (within the window, default 14 days) or UPCOMING, with the cadence, the last run and the kit:

bigbrain [declared]
  DUE       retrospective          P1M        never run  [kit incident, farm evidence]
  UPCOMING  comprehensive-review   P3M        due 2026-12-10 (last run #2372)  [kit review, farm evidence]

The command exits 1 when anything is overdue, so you can gate on it in a script. From inside a project checkout, --project can be left out.

2. Start the run

bob ritual run retrospective --project <project> --dry-run    # what it would open or resume
bob ritual run retrospective --project <project>

run resumes the ritual’s open run issue, or opens one if there is none. It applies the ritual’s kit (the skills and agents the session needs) to the checkout as a provision overlay, then prints the evidence summary, the checklist, the previous run’s findings and the session brief. It refuses (exit 3) a kit that this machine’s role forbids. Pass --no-kit to open the run without the overlay.

To file the issue without starting a session, for example to schedule it, use bob ritual open <ritual> --project <project> (preview with --dry-run). It refuses a second open run of the same ritual.

Drills name what they rehearse:

bob ritual run drill --drill restore                         # a BoB-level drill, held on bigbrain
bob ritual run drill --drill lost-laptop --machine <id>      # embeds that machine's revocation list
bob ritual run drill --project <project> --drill-kind failover
bob ritual run guide-walkthrough --guide first-product       # lead the operator through one guide

3. Gather the evidence

bob ritual prepare <run-issue> --dry-run     # gather and print, post nothing
bob ritual prepare <run-issue>               # post (or replace) the evidence comment on the run

prepare only reports. It posts one evidence comment and replaces it on a rerun. Farm-eligible rituals are also prepared by bob tick (bob ritual prepare --due), so the evidence may already be there when you sit down.

4. Hold the session

Start Claude Code in the checkout and tell it to hold the run. The agent leads; you decide. The brief bob ritual run printed (it is also on the run issue, under How the session runs) has the agent:

1. Open by saying what the ritual is, how long it will take and what your part is.
2. Gather the evidence and walk the checklist itself, without questions.
3. Bring you one recommended plan and one decision: do everything recommended, do part of it, or stop for now.
4. Run the follow-up itself once you say go. It hands you a step only for a login, a vendor page or a decision, with where to go, what to type and what to expect.

If a session hands you a list of findings with a question each, or names a runbook and stops, say “lead the session as the brief says”.

Each finding is filed as its own issue: a bug, req, task (maintenance, #3710), security or todo. A genuine lesson or decision is filed through /journal. The run issue itself is never labelled lesson or decision.

5. Close the run

bob ritual close <run-issue> --finding <N> --finding <N> \
  --no-action "lockfile drift already fixed on master" \
  --journal <N> --dry-run           # check everything and print the closed body
bob ritual close <run-issue> --finding <N> --finding <N> --journal <N>

Every finding has to link an issue or carry a --no-action reason. A run that found nothing closes with --no-findings, which records that fact. A checklist run is refused while nothing on it is ticked. On refusal (exit 3) each problem is named and the run stays open. The closed body carries the delta against the previous run: what was resolved, what recurs, and what is new.

6. Portfolio review: record the decision

A portfolio-review run ends with a decision per project. Write it into the manifest:

bob ritual decide <project> park             # report what would change
bob ritual decide <project> park --apply     # write _meta.portfolio (and the dormant cadence)

The choices are invest, maintain, park and archive. archive also sets active: false, regenerates projects.json and archives the project’s GitHub repo. The repo is never deleted.

Hold the review as a sweep

The manifests are not the whole picture: there are checkouts with no manifest, manifests whose directory is gone, and backups beside their originals. A sweep lists every project directory on every fleet machine and records one outcome for each. Start the run as in step 2, then:

1. Take the inventory. It scans this machine and reaches the others over SSH. A machine it could not reach is named in the last lines.

   bob ritual sweep inventory --write    # one list for the fleet, saved as portfolio.json in the operator repo

2. Decide every row. One outcome each: invest, maintain, park, archive, scrap (delete the local copies) or not-a-project (keep it on disk, leave it out). --with decides a second row with the first, such as a backup beside its original.

   bob ritual sweep decide Sites/old-site scrap --with Sites/old-site-bak
   bob ritual sweep status               # prints the rows still undecided; exit 0 when none are

   Nothing changes on disk or on GitHub yet. Decisions are kept if you stop and run the inventory again later.

3. Carry the decisions out. Read the report first.

   bob ritual sweep apply            # each step it would take; changes nothing
   bob ritual sweep apply --apply    # manifests written, paths corrected, archived repos archived

   A directory decided invest, maintain or park with no manifest gets one through bob ready. A step that cannot run here says why and what to do, and the command exits 1 until none is left.

4. Delete what was decided scrap. Archive every path first, then approve the list. The list deletes nothing until you approve that exact list.

   bob ritual sweep scrap                      # every path, per machine: DELETE, BLOCKED and why
   bob ritual sweep scrap --archive            # copy each path to the archive drive and check the copy
   bob ritual sweep scrap                      # read it again: archived paths now say DELETE … archived as …
   bob ritual sweep scrap --approve <digest>   # the digest the list printed
   bob ritual sweep scrap --apply              # deletes what this machine removes

   The archive drive is declared once, in the operator repo’s config/sweep-archive.json (see the reference). Mount it before --archive. When it is not mounted, the command says so and how to reach it, and archives and deletes nothing. --archive writes one .tar.gz per path, .git included, under <machine>/<path>, reads each one back from the drive and compares it with the directory. A path on another machine is archived from there over SSH. Once a path’s archive is checked, what existed only there no longer blocks it: the archive holds it. With a drive declared, no path is deleted without a checked archive, and a path that changed after it was archived is refused at --apply: run --archive again. To get one directory back, follow the README.md the command keeps on the drive.

   A path is BLOCKED when something exists only there: uncommitted files, unpushed commits, stashes, no remote, a GitHub repo that no longer exists (the checkout is then the only copy), or a plain directory that is not empty. The list asks GitHub once per remote; when GitHub cannot answer, the checkout is UNKNOWN, never a safe delete. Archive it, keep the work (commit and push it), or accept the loss for that row with bob ritual sweep decide <row> scrap --discard and read the list again. A checkout on a laptop is removed by Fleet, not by this command: the prune step of fleet repos sync, tracked in paulirv/fleet#77. Run bob ritual sweep scrap --apply on farm-01 for the farm’s paths.

5. Leave the record. Save the dated audit, file one /journal decision issue for the status changes, and write the decisions into the run issue:

   bob ritual sweep audit --write                              # audits/portfolio-audit-<date>.md in the operator repo
   bob ritual sweep record <run-issue> --journal <decision-issue> --apply

   Commit the operator repo (portfolio.json, the manifests, the audit), then close the run as in step 5.

7. Docs review: read the docs as a person

docs-review is the monthly pass over the docs that make docs-check cannot make. A project holds it once its manifest declares it with the checklist:

{ "name": "docs-review", "cadence": "P1M", "checklist": "docs-review-checklist" }

Hold it like any run, with three differences:

1. The packet does the counting. bob ritual prepare <run-issue> gathers the stale and aging pages, the commands no how-to runs, what was added since the previous run that no page names, and how far the live site lags the latest build. It also names the tutorial this run walks: the one walked least recently, chosen from the closed runs, so nothing needs remembering.

2. Walk the checklist. The run issue carries the nine items of docs-review-checklist at its version. The runbook says how to assess each one. Walk the named tutorial in a scratch directory, exactly as written; every step that does not work as the page says is a finding.

3. Restamp in one PR. Each page you re-read and found true gets last_reviewed: <today> in its frontmatter. Commit them together and put Refs #<run-issue> in the PR body, so GitHub lists the PR on the run:

   git switch -c docs/docs-review-<run-issue>
   # edit last_reviewed on each re-verified page
   git commit -am "docs(docs-review): re-verify <N> pages (#<run-issue>)"
   gh pr create --title "docs(docs-review): re-verify <N> pages" --body "Refs #<run-issue>"

Close it as in step 5. Each finding links a req (a page the product needs), a bug (a page that misdescribes what shipped) or a todo (something only a person can do), or carries --no-action. Never restamp a page you did not read.

Verify

bob ritual due --project <project>     # the ritual now shows its last run and next due date
gh issue view <run-issue>              # closed, findings linked, delta recorded

Related

• Rituals reference: cadences, kits, collectors, the run-issue format and the release gate.
• Farm Tick: what prepares evidence overnight.