You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4e22672
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: src/bridges/guidance_block.ts
+1-3Lines changed: 1 addition & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -35,9 +35,7 @@ export function buildGuidanceBody(fallbackToolClause: string, opts: GuidanceOpti
35
35
'Failure shapes to catch yourself in, and the command that replaces each:',
36
36
'- not knowing which command answers a question you can already state in words → `answer "<question>"`, which runs the right command and refuses rather than guess',
37
37
'- a shell text search with context flags to find a function body → `read "file::symbol"`',
38
-
'- paging one function with view/view_range → `read "file::symbol"`',
39
-
'- issuing sequential or overlapping line-range reads across a file (paging) → `read "file::symbol"` / `outline file` / `skeleton file` / rg <pattern> <file>',
40
-
'- a read refused by a `[tg]` deny, retried with a shifted range, different lines, or another read tool → never retry reading the file at different lines; run the command the deny names or use bash-output / token-goat read',
38
+
'- paging a function/file or receiving a `[tg]` range denial → stop range reads; run its exact command, `read "file::symbol"` for a definition, `read "file@start-end"` for a window, `skeleton file` for structure, or `grep "<pattern>" file -C 15 --symbol` for an excerpt',
41
39
'- reading a symbol plus chasing its callers and containing doc section as separate reads → `brief "file::symbol"`',
42
40
'- reading one heading of a large doc → `section "file::Heading"`',
43
41
"- searching for a symbol's callers → `refs file::symbol --callers`",
Copy file name to clipboardExpand all lines: src/canonical_skill.md
+7-9Lines changed: 7 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -116,21 +116,19 @@ Paths go in relative to the working directory; `waste` prints absolute ones, so
116
116
117
117
## Anti-Paging Trap
118
118
119
-
When encountering sequential read suggestions or denials (such as `Sequential line-range paging detected`), do not attempt to page through a file using adjacent line-range slices (e.g. `1-100`, `101-200`, `201-300`). Paging line-by-line burns tokens, discards structural context, and triggers hook guard denials.
120
-
A shrunk, grown, or shifted Read range after this deny is also denied; switch to token-goat, do not retry the Read tool.
121
-
122
-
Instead, immediately switch away from line paging to AST/symbol navigation or targeted searches:
123
-
-**AST / Symbol Navigation:** Run `token-goat symbol <name>` or `token-goat read "file::symbol"` to pull the exact function, class, or method definition.
124
-
-**Structural Overview:** Run `token-goat skeleton <file>` or `token-goat outline <file>` to map file symbols, line ranges, and boundaries before reading.
125
-
-**Targeted Grep / Python:** Use targeted ripgrep (`rg <pattern> <file>`) or structural AST queries (`ast-grep`), or targeted python scripts to locate the specific line or definition without blind window sliding.
126
-
-**Document Sections:** Use `token-goat section "file::Heading"` for markdown and documentation rather than paging paragraphs.
119
+
If a paging notice or `[tg]` range denial appears, stop Read/view line ranges; do not retry with a shifted or resized window. Run the exact token-goat command named by the denial first.
-**Answering the gate with "probably not" instead of a command.** The gate is a question with a checkable answer, not a disposition. If you cannot name which command would have worked, you have not answered it -- and `token-goat stats` will show the flat counts that prove it.
131
130
-**Treating a batch as one gate.** Five reads issued in one message are five gates, not one. Batching is a latency optimisation; it does not pool the token cost.
132
131
-**Using `symbol` as a grep.**`symbol NAME` resolves a definition. When you want every *use*, that is `refs file::symbol --callers`; when you want a concept rather than a literal string, that is `semantic`. Reaching for the wrong one and then falling back to a wide search spends the cost of both.
133
-
-**Falling into the paging trap.** Paging through a file line-by-line with sequential range reads is an anti-pattern. When warned or denied for sequential paging, switch immediately to AST/symbol navigation (`token-goat symbol`, `token-goat skeleton`, `token-goat outline`) or targeted python/grep.
134
132
-**Slicing a file that was never indexed.** A file created, generated, or left untracked this turn has no index entry, so a slice command returns nothing and reads as "not there" rather than "not indexed". That case is an explicit exemption -- read it directly and move on instead of retrying the slice.
135
133
-**Re-running a command to see output you already have.** Captured output is addressable by ID via `bash-output`/`web-output`/`mcp-output`, and anything cached this session is reachable with `recall`. Re-running is the most expensive way to scroll up.
136
134
-**Writing tool or binary names into an agent's `tools`/`allowed-tools` frontmatter.** Shell binaries and editor programs are invoked *through* the shell tool; they are not tool identifiers. Instruction-file loaders harvest such names into an allowlist and then warn that every one is unknown -- which is why the gate text above deliberately names none.
0 commit comments