elias/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-06-30 19:00:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(code-tour): document ref-field semantics to prevent PR-tour file-not-found (#2273)

Browse Source 
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.
This commit is contained in:
Carlos Carvallo 2026-06-30 02:38:22 +01:00 committed by GitHub
parent 237b0b9008
commit d178db82a2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 17 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
skills/code-tour/SKILL.md
View File

@ -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