From d178db82a2211f9a0f61e016e144a4fe695f7ffa Mon Sep 17 00:00:00 2001 From: Carlos Carvallo Date: Tue, 30 Jun 2026 02:38:22 +0100 Subject: [PATCH] docs(code-tour): document ref-field semantics to prevent PR-tour file-not-found (#2273) The code-tour skill mentioned the CodeTour 'ref' field only in an example, with no explanation of its behavior. CodeTour resolves each step's file content from the git revision named by 'ref' (not the working tree) whenever ref differs from HEAD, so any file that does not exist at that revision fails to open with 'The editor could not be opened because the file was not found' - even though the file is present on disk. This bit a generated PR tour where ref was set to the base branch (develop): every file ADDED by the PR is absent on the base, so all new-file steps 404'd while the tour tree and comments still rendered, making the cause non-obvious. Adds a 'The ref Field' section explaining the resolution behavior and the rule that PR tours must pin ref to the branch head (never the base), plus a validation step to confirm every referenced file exists at the chosen ref. --- skills/code-tour/SKILL.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/skills/code-tour/SKILL.md b/skills/code-tour/SKILL.md index 34a9629a..fc82ee69 100644 --- a/skills/code-tour/SKILL.md +++ b/skills/code-tour/SKILL.md @@ -93,8 +93,25 @@ Before finishing: - every referenced path exists - every line or selection is valid - the first step is anchored to a real file or directory +- the `ref` points at a branch or commit that actually has every file the tour references (see below) - the tour tells a coherent story rather than listing files +## The `ref` Field + +`ref` ties the tour to a git branch or commit. It matters more than it looks: when `ref` is not the branch the reader has checked out, CodeTour opens each step's file from that revision in git, not from the files on disk. If a file is not in that revision, the step will not open — the reader sees *"The editor could not be opened because the file was not found"* even though the file is sitting right there. The tour and its comments still show, so the real cause is easy to miss. + +Pick `ref` by tour type: + +| Tour type | Set `ref` to | +| --- | --- | +| PR tour | the PR branch — never the base branch | +| Onboarding / architecture | the branch the reader will be on (often `main`), or leave it out | +| Not sure | leave `ref` out, so CodeTour reads files straight from disk | + +The PR case is the common trap: a PR usually adds new files, and new files do not exist on the base branch yet. Point `ref` at the base (e.g. `develop`) and every step on a new file fails to open. + +Before finishing, confirm each step's file actually exists at the `ref` you chose. + ## Step Types ### Content