Run Unstructured Work with bob do

Run unstructured work with bob do

Use bob do for work with no requirement behind it: a spike, an hour poking at something, or a “should we even do this?”. The run refuses to start working until you have said what the hour will produce. For why it is built this way, see The bob do machine.

Before you start

• No warp-drive run is active in this checkout. bob do writes files, so it refuses to start beside one and names the run it found. Let that run finish or stop it with bob warp stop.
• The run’s state lives in .claude/.do-state.json.

Steps

1. Start the run and frame it. Give the question as one quoted line, and name the artifact it will produce:

   bob do "should we cache the fleet feed?" --artifact decision --budget 45m

   The artifact must be one of decision, lesson, doc, spike, issue-set or discard. Anything else is refused and the run stays in framing. Without --artifact the run also stays in framing. Frame it later with:

   bob do transition framed --data '{"artifact":"spike"}'

2. Work inside the budget. --budget takes minutes (45 or 45m), tokens (200000t) or thousands of tokens (200k). Without it the budget is _workflow.do_budget_minutes (default 60). Check the run at any time:

   bob do status

   When the budget is spent, the next bob do call moves the run to landing with budget_exhausted: true. It does not wait for you.

3. Stop working when you have enough:

   bob do transition worked --data '{"enough":"the numbers answer it"}'

4. Land the artifact. Name it, and the gate reads it back. Use an issue number for decision, lesson, spike or discard, issues for an issue-set, or a path under docs/ for a doc (or a spike):

   bob do transition landed --data '{"issue":3021}'
   bob do transition landed --data '{"path":"docs/explanation/fleet-feed-cache.md"}'

   An issue must carry the artifact’s label and name the question. A doc must be committed and pass the docs check. The evidence for each type is listed in Artifact evidence.

5. Record what prompted it. Link the artifact and the prompt to each other (for example, a comment on each issue naming the other), then:

   bob do transition recorded --data '{"prompted_by":"#2990"}'

   prompted_by can also be a file in the checkout, such as a brief, or none. The run ends done, and bob do status shows the outcome and the artifact.

When the answer is “no”

If the work shows the thing is not worth doing, discard the run. This ends it successfully, but only after a decision is on record:

1. File the decision with /journal decision. Say why not, and quote the run’s question in it.

2. Discard the run with that issue’s number. You can do this from working or landing:

   bob do transition discard --data '{"decision":3021}'

The gate reads the issue back. It must exist, carry the decision label and name the question. The run then ends discarded and exits 0.

To abandon a run

bob do stop

This removes the run’s state and frees the checkout for warp-drive. Nothing is recorded, so if the hour answered a question, prefer discard with a decision.

Verify

• bob do status prints the phase, the question, the artifact and the budget used.
• While a do run is active, bob warp start exits 5 and warp-drive’s init exits 3, both naming the run.

Reference

• bob do reference: events, payloads, the artifact evidence and the state fields.
• bob do in the CLI reference: every flag and exit code.
• The bob do machine: the phases, the framing gate and why discarded is a success.