Skip to content

Commit 4e22672

Browse files
committed
fix: streamline paging denial guidance
1 parent 94f53ed commit 4e22672

11 files changed

Lines changed: 121 additions & 99 deletions

‎src/bridges/guidance_block.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,7 @@ export function buildGuidanceBody(fallbackToolClause: string, opts: GuidanceOpti
3535
'Failure shapes to catch yourself in, and the command that replaces each:',
3636
'- 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',
3737
'- 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',
4139
'- reading a symbol plus chasing its callers and containing doc section as separate reads → `brief "file::symbol"`',
4240
'- reading one heading of a large doc → `section "file::Heading"`',
4341
"- searching for a symbol's callers → `refs file::symbol --callers`",

‎src/canonical_skill.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -116,21 +116,19 @@ Paths go in relative to the working directory; `waste` prints absolute ones, so
116116

117117
## Anti-Paging Trap
118118

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.
120+
Use the one surgical command that fits:
121+
- Definition → `token-goat read "file::symbol"`.
122+
- Denied window → `token-goat read "file@start-end"`.
123+
- Structure → `token-goat skeleton <file>` (or `outline`).
124+
- Text excerpt → `token-goat grep "<pattern>" <file> -C 15 --symbol`.
125+
- Markdown heading → `token-goat section "file::Heading"`.
127126

128127
## Anti-Patterns
129128

130129
- **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.
131130
- **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.
132131
- **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.
134132
- **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.
135133
- **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.
136134
- **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

Comments
 (0)