Coming Back to a Project

The first hour back. Your First Product with BoB ends on a Friday with a release. This tutorial starts when you come back to the same project after a real gap: days or a week, while the loop, and maybe the farm, kept working. You will walk the same routine every time you return, in the same order, and end with one ranked choice of what to do first. Every command below comes from the Coming Back explanation, which also covers why each stop comes where it does.

← Tutorials · docs home

What you will do

Before the gap, you leave work behind on purpose: two new requirements, a plan and a run that you do not watch. After the gap, you spend one hour on a fixed routine:

Stop	Question	Time
2	Is this machine current, and what changed in BoB?	10 min
3	What happened here, and is the project healthy?	5 min
4	What is waiting on me?	5 min
5	Where is the plan?	5 min
6	What did the runs record?	10 min
7	What did the sessions learn, and what have I never tried?	10 min
8	What is overdue?	3 min
9	What did the farm do?	5 min
10	What do I do first?	5 min

That is under an hour. The routine is the same one /status and /what-next implement, so you are learning to read the tools, not a separate habit.

Before you start

Finish Your First Product with BoB first. This tutorial runs on the same hello-links project and assumes its two capabilities (#1 Short links, #2 Manage links) exist.
A real gap. Leave at least two days between Stop 1 and Stop 2. The routine only makes sense when you have genuinely forgotten the details.
A farm is optional. Stop 9 shows what to look for if you delegate work to one. If you do not, it takes a minute and finds nothing.

Issue numbers below are examples: the plan is #12 and the todo the loop files is #13. Your numbers will differ, because every report the loop files is an issue too. Use the numbers your commands print.

Part 1 — Before the gap

Stop 1. Leave work behind

Open Claude Code in hello-links (claude -a3) and file two requirements under Manage links. Then, in a shell, plan them and start a run you will not watch:

/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

Say yes when /requirement asks whether each requirement is approved. Use the plan number bob plan build prints in the bob warp start line.

What you should see.

Two new req issues, labelled approved and area:manage-links, each ending with Part of #2. The email requirement also says what it depends on.
bob plan build prints the new plan’s number.
bob warp start runs its preflight, then names the tmux session the run started in.

What just happened. The run works the plan in order while you are away. Expiry is ordinary code, so the loop can finish it. The email needs a provider account and an API key, which only you can supply. The loop does not guess on a decision like that. It files a todo for you, skips the work and ends the run.

Checkpoint. bob plan status 12 lists both requirements, and tmux ls shows the run’s session. Now close the laptop and come back in a few days.

Part 2 — The first hour back

Stop 2. Bring the machine up to date

Do this in a plain shell, before you open Claude Code:

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

Write down the version line from the first bob doctor before you run the update.

What you should see.

The first bob doctor ends with a verdict, and its version line shows the release you left on.
bob update --dry-run names the tag it would move to, and changes nothing.
bob update fetches, fast-forwards the BoB source checkout, deploys it and runs the doctor again. If you are already on the newest release, it says so and changes nothing.
The last bob doctor shows the new version line.

What just happened. Every later stop runs on BoB, so BoB goes first. bob update refuses to run while a Claude Code session is open on the machine, because redeploying the settings would silence the hooks in that session. That is why this stop comes before Claude. If it refuses for another reason (a dirty checkout, a failed fetch), it names the reason and changes nothing.

To see what changed, open CHANGELOG.md in the BoB source checkout and read the sections between your old version and your new one.

Checkpoint. The last bob doctor reports no drift, and you can name one change from the changelog.

Stop 3. Read the catch-up

Open Claude Code in hello-links (claude -a3) and run:

/status

What you should see. One report in two parts:

Catch-up: recent activity (commits by type, issues closed), the status of each capability, and one Health: line that reads on-track, at-risk or off-track, followed by the counts it was derived from.
Next up: the ranked list of what to work on. Your todo appears in its own “Your action items” section.

What just happened. One read of the tracker and the commit history replaced twenty minutes of scrolling. With the email requirement blocked, the health line is probably at-risk: the rubric counts one blocked item as a risk. The rest of the routine fills in the detail behind each line of this report.

Checkpoint. You can say, without looking again, what closed while you were away and what the health line says.

Stop 4. Clear your own queue

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

The second line opens the todo the loop filed. Read it: it says in one sentence what is blocked and why, then lists numbered steps, then Blocked by #NN. Do the steps (for the email requirement: create the provider account and store its API key where the todo says). Then run the third line.

What you should see.

gh issue list --label todo lists the todo the run filed, assigned to you.
After the edit, gh issue view 13 shows the completed label. The issue is still open.

What just happened. completed is the resume signal, not closing. The next loop run reads the label, removes blocked from the issue the todo names, closes the todo with a comment, and picks the work up. If you decide the work is no longer wanted, close the todo without completed: the loop then treats the work as cancelled and never resumes it.

Checkpoint. No open todo is left without either the completed label or a decision to close it.

Stop 5. Find the plan

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

What you should see. The plan you built in Stop 1, with the expiry requirement checked and the email requirement runnable. A todo labelled completed no longer gates anything. If you skipped Stop 4, the email requirement shows as gated, and the status names the todo.

What just happened. The plan is the order you committed to before you left, so it outranks anything that joined the queue since. bob plan status only reads, so run it as often as you like.

Checkpoint. You know the plan’s number, and how many of its items are runnable.

Stop 6. Read the records

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

Open the newest session report (gh issue view <number>) and read it in full.

What you should see.

One session report for the run you started in Stop 1. It lists the requirement it finished, the one it skipped, the todo it filed and the tokens it used.
One chunk report for each commit the run made.
Your decision and lesson from the first week, plus any the run filed.

What just happened. Reports say what happened. Decisions and lessons say what to do next time. BoB never puts both labels on one issue, so each list stays short enough to read. The session report is the fastest way to confirm what /status summarised.

Checkpoint. You can name the commit that delivered expiry, from its chunk report.

Stop 7. Recall what the sessions learned

The first line provisions the recall skill once. The other two read the loop’s notes and tour the tools this project has never used:

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

Then, back in Claude Code:

/memory-recall expiry

What you should see.

bob provision add skill memory-recall adds the skill to the project’s manifest. If the project has it already, it says so.
The loop-notes line prints the quirks the loop recorded here, such as a flaky test or a command that needs a flag. It may print nothing.
bob tour prints counts of unknown, parked and in-use items, then lists each unknown item with one line on when to use it and the command to try.
/memory-recall expiry lists the memories that match, best first, or says none match.

What just happened. The tracker holds what the team knows. Memory and loop notes hold what the sessions learned, which never reaches an issue. Every new run starts with the loop notes, so it is worth knowing what they say. The tour is the reverse view: tools you have and have never used. Try one with bob tour --tried <item>, or decide against it with bob tour --park <item>.

Checkpoint. You have read the loop notes (or confirmed there are none), and marked one tour item as tried or parked.

Stop 8. Check what is overdue

bob ritual due

What you should see. One line per ritual (retrospective, dependency audit, vision review and others), each graded overdue, due, upcoming or unknown. A ritual’s last run is read from its closed ritual-run issues, and a ritual that has never run is due. On a new project like hello-links, that is most of them. If it says the directory is not a managed project, run bob ritual due --project hello-links.

What just happened. Rituals are the one kind of work no queue surfaces on its own: nobody files them, they fall due. A project that sat untouched for two weeks is the one most likely to have missed one. An unknown ritual means its run history could not be read. It is never counted as overdue.

Checkpoint. You know whether anything is overdue. If something is, it goes to the top of Stop 10.

Stop 9. Check what the farm did

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

What you should see.

If the farm worked on this project: a plan titled Flight plan: farm (unattended), with one comment per night headed ## bob tick <date>, plus merged PRs it opened and merged when CI passed.
bob status --scope fleet --no-live lists each fleet machine with when its snapshot was taken, and the state of each project on it. stale marks a machine that has not reported for more than a day.
With no farm, no farm plan and no PRs, and only your own machine in the fleet view.

What just happened. You can tell a farm run from your own by where it came from: the farm builds its own plan, comments its digest on it, and never pushes to main directly. It opens a PR and merges only on green CI. Your own Level 3 run merges directly and has no PR. An empty result is an answer too: everything you read in Stop 6 came from your own runs.

Checkpoint. For every merged change since you left, you can say whether you or the farm made it.

Stop 10. Decide what to do first

Before you run anything, write down your own first choice from the evidence, in this order:

an overdue ritual from Stop 8;
an open todo from Stop 4 you have not handled;
the active plan’s runnable items from Stop 5;
the rest of the approved queue: highest priority first, then work that unblocks other work, then bugs before requirements.

Then ask the tool:

/what-next

What you should see. The same order. Any overdue ritual is at the top, then your action items, then one row for the plan (flight-plan #12 — 1 runnable of 2, resume with warp-drive --flightplan 12), then any loose approved work.

What just happened. /what-next ranks with the same rules you just used, so the tool and your reasoning agree. If they do not, one of the stops has evidence you skipped: find it before you overrule the tool.

Checkpoint. Your written choice matches the top row of /what-next. Start it: for this tutorial, that is /warp-drive --flightplan 12, which picks up the email requirement now that its todo is completed.

Where you are now

You came back to a project you had half forgotten. In under an hour you knew the machine was current, what happened while you were away, what was waiting on you, where the plan stood, what the runs and sessions recorded, what was overdue and what the farm did. You also made one choice, the same one the tool made. Do the same routine every time you come back, in the same order. After a few times it takes twenty minutes.

Where to go next

Coming Back to a BoB Project: why each stop comes where it does.
Farm Tick (the night shift): what the farm runs, and how to delegate work to it.
Rituals: every ritual, its cadence and how to hold one.
Todo format contract: what a todo contains and how completed resumes work.

Next tutorial: Holding a Ritual — One monthly retrospective on a small product, start to finish: declare it, see it come due, open the run, gather the evidence, hold the session with its kit, and close it with findings and lessons that last.