How BoB surfaces its own capabilities

How BoB surfaces its own capabilities

There is functionality in BoB its owner does not use only because he does not know it is there. The 2026-09-10 architecture review (BoB at 1.264) put names to it: bob swarm, cascade-engine (since retired, #3042), tdd-flow, loop-primitive, bob reap, bob mirror, trace-mining, memory-audit and bob project (since retired, #1752) are wired and tested but rarely invoked, and six registry skills have never been provisioned anywhere. The discoverability capability (#2031) answers that with BoB teaching itself — and this page explains the shape of the answer, starting with its first piece, bob tour (#2075).

Evidence, not a list

A “things you might have missed” page written once is out of date by the next release, and it says nothing about this project. BoB already records what sessions actually use: the session evidence ledger (scripts/evidence/ledger.js, #1131) appends one event per skill, slash command or agent invocation from a PostToolUse collector, into the project’s gitignored .claude/session-ledger.jsonl. ledger.js unused --universal already answers the question the tour needs — which items declared in this project’s provision manifest, plus the universal ones every project gets, have zero events.

So bob tour adds no evidence of its own. It reads the ledger, joins each never-invoked item to what the registry already says about it — the first sentence of its description and its recommended_for list, or the summary of its row in scripts/bob/commands.json for a CLI noun — and prints one line per item: item — when — try: <command>. Change a skill’s description and the tour changes with it.

Absence is measured, not assumed. A project that adopted the ledger yesterday has no events, and a tour over an empty ledger would call everything unknown. When the ledger holds no events at all, the tour first runs the transcript backfill (backfill-transcripts.js --apply), which mines past Claude Code transcripts for the same invocations and records them with source: "backfill". A ledger that has any history is never re-mined; --no-backfill skips the step.

The seed: what the ledger cannot see

The ledger records tool invocations — skills, commands, agents. It never sees bob reap typed in a shell, or a script run by another script. Those are exactly the items the review flagged, so the tour carries a version-controlled seed, scripts/tour/seed-2026-09-10.json: the review’s unknown bucket, with a type of skill, command, cli (a bob noun) or script, and an explicit when/try line where no frontmatter exists. The seed is the tour’s initial state. It joins the ledger’s list in every project, so its items stay on the tour until the owner has done something about each one. An item retired since — the review’s one script, cascade-engine (#3042) — leaves the seed, and the tour drops it from a project’s state file too.

Three grades, and no fourth

The rule recorded on 2026-09-10: non-usage is not evidence of uselessness. An item nobody invoked may be the right tool for a problem that has not come up yet, or one its owner never heard of. The tour therefore never labels anything useless, dead or unneeded. Every item gets one of three grades:

Grade	Means	Comes from
unknown	never invoked here in the window, and the owner has not recorded a choice	the ledger holds no events for it
parked	the owner looked at it and chose not to use it, on a date	bob tour --park <item>
in-use	invoked, or tried once	ledger events, or bob tour --tried <item>

A demotion decision — removing an item from a manifest, retiring a skill — is a separate judgment with its own evidence (the orchestrator’s would-remove, #1879). The tour’s job ends at making the choice visible and recorded.

The owner’s record

What the owner did with each item lives in the project, in .claude/.tour.json (bob-tour-state/1): the seed it started from, and tried / parked maps of item → date. It is written only by --tried and --park; reading the tour never writes it. --tried clears a park and --park clears a try, so the latest choice is the one that counts. A corrupt state file is an error, never silently replaced.

Both flags also accept a registry item the project has never provisioned, so a recommendation can be declined on the record. The provisioning nudge /vision and /groom print (gap-detect.js divergence) reads the same parks: a parked item — a would-add recommendation or a declared item never invoked — is listed under excluded with reason parked and its date instead of being nudged, and the nudge exits 0 once every item is provisioned, global or parked (#2088).

The capability’s success metric reads straight off this record: every item of the 2026-09-10 unknown bucket either tried once or consciously parked.

Where it goes next

The tour is the source; the rest of the capability reads from it rather than keeping its own list:

• BoB in one day (#2076) — the tutorial generated from the workday scenarios, for learning the everyday path before the long tail.
• Did-you-know on bob viz (#2077) — one tour item at a time, where the owner already looks.
• The orchestrator’s nudge (#2078) — provisioned-but-never-invoked items alongside the never-provisioned ones its why: line already surfaces.

This page is refreshed by the last requirement of the capability, when those pieces land.

See also

• Skill evolution — the tour measures whether an item is used; skill evolution measures whether it is good, and the no-trigger records the ledger keeps are one of its trace sources.
• bob CLI reference — bob tour flags, exit codes and the bob-tour/1 document.
• The bob CLI — how a command like bob tour is added.