Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
index 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