Comment by cyrusradfar

4 days ago

Hi! Thank you :) Great question and it's one that's full of assumptions so tell me where you think I'm wrong.

Tours are stored as a flat file (JSON). When you open a tour, you open it with the Agent and on, re-opening, it goes through re-validation (as is done during the tour). In the case where lines shift in files because the file includes start/end ranges and line text (verbatim), this will cause the tour to be invalidated and the Agent will need to rebuild it. There are a lot of "dead code" cases where this won't catch a tour update, today.

The tour file contains a ton of meta information, as well, so each time the Agent opens it -- it could rebuild the tour with the same intents. The original user request, synthesized request, success criteria, concepts that are going to be taught.

This is a first pass solution for now. If there's more interest, there's a much more interesting tech solution with managing pointers to references and invalidating the tour on a broader range of criteria.

Part of what I need to learn is:

  - A. Are tours something that folks use as ongoing "interactive" documentation, e.g. a set of onboarding tours
  - B. Are tours ephemeral that folks use to hash out how to approach a feature, bug or review a PR.

At the moment, it's more optimized for B as that's how I've been using it but A is a very cool use case because one could imagine opening a new repo and having N tours that you can just start up. I was considering reaching out to open source projects to create tour-files and request a PR after they confirm interest (not spam them) to test A.