The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs(code-tour): document ref-field semantics to prevent PR-tour file-not-found (#2273)
Carlos Carvallod178db82a221
diff --git a/skills/code-tour/SKILL.md b/skills/code-tour/SKILL.mdindex 34a9629aa..fc82ee690 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