Coming Back to a BoB Project

Coming Back to a BoB Project

The hour after time away. A Week in the Life of a BoB Product ends with a release and a retrospective. This page starts a week or two later, when you open the same project again. You have forgotten what was in flight. The loop may have run while you were gone, and the farm may have run at night. BoB changed underneath you too. This page explains why the first hour back is a fixed routine, and why each stop comes in the order it does. The Coming Back to a Project tutorial walks the same hour step by step, and takes every command below from this page.

Why a routine, and why this order

Coming back is the moment you are most likely to act on a stale picture. You remember what you meant to do next, not what happened. A fixed routine replaces memory with evidence, and the order matters. Each stop answers a question the next one depends on:

1. Is the machine current? Every later command runs on BoB, so it goes first.
2. What happened here? One catch-up report, before you read anything by hand.
3. What is waiting on me? Your own queue, because nothing gated behind it can move.
4. Where is the plan? The order you committed to before you left.
5. What did the runs record? Session summaries, chunk reports and journal issues.
6. What did the sessions learn? Memory, loop notes and the tools you never touched.
7. What is overdue? Rituals, which no queue will ever surface on its own.
8. What did the farm do? Work that happened while nobody was watching.

Then you decide. The last section explains why the decision uses the same order /what-next uses, so the tool and your own reasoning agree.

Why the tutorial leaves work behind on purpose

A real gap always leaves something in flight: a run that finished without you, a decision only you can make, a plan half done. To practise coming back, you need the same. So before the gap, the tutorial files two more requirements under the hello-links Manage links capability, plans them and starts a run:

• Link expiry is ordinary work that the loop can finish on its own.
• A weekly visit email needs an email provider account and an API key. Only a human can supply those, so the loop usually files a todo and skips the work.

/requirement Links can expire: an optional expiry date after which the short code returns 410. Part of #2.
/requirement Email me a weekly visit summary for every link. Part of #2. Depends on the expiry requirement.

bob plan build --area manage-links
bob warp start --flightplan 12 --level 3

Then you leave, for at least two days. The run finishes (or stops at the todo) without you, which is exactly the situation the routine is for.

Why the machine comes first

While you were away BoB kept shipping. A new release can change what a command prints, add a gate or retire a flag. If you read your project through an old BoB, you can misread it: a missing surface looks like a broken project.

bob doctor answers “does this machine match the BoB source it was deployed from?” Its version line says which release you are on. bob update moves you to the newest release: it fast-forwards the source checkout to the newest stable tag, deploys it and runs the doctor again. It refuses while a Claude Code session is running on the machine, because redeploying the settings would silence the hooks in that session. That is why this stop runs in a plain shell, before you open Claude.

bob doctor
bob update --dry-run
bob update
bob doctor

The difference between the two version lines is what changed. The release notes for every version in between are in CHANGELOG.md in the BoB source checkout. Read the sections between your old version and your new one.

Why the catch-up report comes before any reading

You could start by scrolling the issue list. But the list is sorted by date, not by what matters, and it cannot tell you whether the project is healthy. /status (the short form of /what-next --report) reads the whole tracker and the commit history once, and prints:

• recent activity: commits by type, and the issues that closed;
• capability status: how far each capability’s requirements have got;
• one health line: on-track, at-risk or off-track, derived from blocked counts and acceptance-criteria progress, never from anyone’s opinion;
• what to work on next, ranked (the same list /what-next prints).

/status

Every later stop fills in detail behind one line of this report. Read it first so you know which details matter.

Why your own queue comes before the plan

The loop never waits for you. When it hits something only a human can do (a paid account, an API key, a sign-off), it files a todo issue, skips the blocked work and carries on. By the time you come back, your todos are the one queue that nothing else can drain. Every item gated behind a todo stays blocked until you act.

The resume signal is a label, not a closed issue. When you have done the action, add completed to the todo. The next loop run reads the label, removes blocked from each issue the todo names in Blocked by #NN, and picks the work up again. A todo closed without completed means “cancelled”: the work it gated is never resumed.

gh issue list --label todo --state open
gh issue view 13
gh issue edit 13 --add-label completed

Why the plan comes before the queue

Before you left, you wrote an order down: the flight plan. The approved queue may have changed since then, but the plan is still the order you committed to. So the plan comes before any queue. bob plan status reads the plan and the issues it names, and says which items are done, which are runnable now, and which are gated by a todo, waiting on a dependency or withheld.

gh issue list --label flight-plan --state open
bob plan status 12

A plan item marked gated names its todo. That is the link between this stop and the previous one: completing the todo is what makes the item runnable again.

Why the records come before memory

Each loop run leaves three kinds of record in the tracker:

• a chunk report per commit (chunk-report): what was built, and what failed before it passed;
• a session report per run (session-report): what the run finished, what it skipped and why, and what it cost;
• decision and lesson issues, filed with /journal when the run found something worth keeping.

Reports are execution records: read them for what happened. Decisions and lessons are knowledge records: read them for what to do differently. BoB never puts both labels on one issue, so each list stays short enough to read.

gh issue list --label session-report --state all --limit 5
gh issue list --label chunk-report --state all --limit 10
gh issue list --label decision --state all --limit 5
gh issue list --label lesson --state all --limit 5

Read the newest session report in full. It names every item the run finished, skipped or blocked, so it explains most of what /status summarised.

Why memory and the tour come next

The tracker holds what the team knows. Two other stores hold what the sessions learned about this project:

• memory: facts and preferences Claude saved across sessions. /memory-recall retrieves only the memories that match a query, instead of the whole index.
• loop notes: the quirks the loop found the hard way (a flaky test, a command that needs a flag). Every new loop run starts with them, and you can read them too.

bob tour answers the opposite question: what is provisioned here that nobody has ever used? Coming back is a good moment to try one of those tools, or to park it on purpose.

bob provision add skill memory-recall
node ~/.claude/scripts/warp-drive/loop-notes.js list
bob tour

/memory-recall expiry

Why rituals are a separate stop

A requirement waits in the queue until someone works on it. A ritual (a retrospective, a dependency audit, a vision review) is different. It is due on a schedule, and nothing files it for you. /status lists overdue rituals first, but it is worth asking directly: a project you have not touched for two weeks is the one most likely to have missed one.

bob ritual due

Each ritual is graded overdue, due (never run, or due within 14 days), upcoming, or unknown (its run history could not be read). An unknown ritual is never counted as overdue.

Why the farm gets its own stop

If you delegate work to the farm (approved requirements labelled farm), the farm tick may have worked on this project every night you were away. Its work looks like yours: commits, reports, closed issues. What makes it different is where it came from:

• the tick builds its own flight plan, titled Flight plan: farm (unattended), never your named plan;
• it comments one digest per night on that plan, headed ## bob tick <date>;
• an unattended run never pushes to main. It opens a PR and merges it only when CI passes, so its work arrives as merged PRs, while your Level 3 runs merge directly.

The fleet snapshot shows the same night from the machine side: when each machine last reported, and the state of each project on it.

gh issue list --label flight-plan --state all --search "farm (unattended) in:title"
gh pr list --state merged --limit 10
bob status --scope fleet --no-live

If you have no farm, this stop takes a minute and finds nothing, and that is a useful answer too: everything in the tracker came from your own runs.

Deciding what to do first

The routine gathers evidence; it does not choose. Choose with the same order /what-next uses, so the tool and your reasoning agree:

1. Overdue rituals and due credential rotations come first. They are schedule lapses, and nothing else will surface them again.
2. Your own todos come next. Each one frees work that nothing else can free.
3. An active flight plan comes before loose queue items, because it is the order you already committed to. Its runnable remainder is one row: resume it with --flightplan.
4. The rest of the approved queue, by priority (p1-critical first), then items that unblock others, then bugs before requirements at equal priority.

/what-next

Write down your own first choice before you run it. If /what-next agrees, start. If it disagrees, one of the stops above has evidence you skipped. Find it before you override the tool.

Related

• /what-next: the ranking and the report in full
• Farm Tick (the night shift): what the farm runs and how it merges
• Rituals: the ritual schedule and grading
• Todo format contract: what a todo contains and how completed resumes work