token-efficient-execution ยท diff
git:20261010.aeeed13 to git:20261018.ddb07f4
35 added, 67 removed. Audit A to A.
---
name: token-efficient-execution
# prettier-ignore
- description: Minimize token use without losing correctness, completeness, or requested detail. Use for any non-trivial task, especially code changes, repository work, research, multi-step reasoning, and tool-assisted workflows, or when the user asks for concise, low-cost, or token-efficient work.
+ description: Spend the fewest tokens, tool calls, and words that still give a correct, complete, verified result. Use for every task with more than one step, even when the user does not mention cost, including code changes, debugging, refactoring, repository searches, multi-file edits, research, CI and build work, and any tool-assisted workflow, and whenever the user asks for concise, quick, cheap, or token-efficient work. Not for a one-step answer that needs no tools, such as arithmetic, a greeting, or a short fact.
---
# Token-Efficient Execution
- Use the least information, reasoning, tool calls, and output that give a correct, complete, maintainable result. Efficiency limits effort. It never replaces needed reasoning, verification, or requested detail.
+ Use the least context, tool calls, reasoning, and output that give a correct, complete, maintainable result. Cut waste, never substance. Waste is repeated reads, broad searches, speculative calls, narration, and unrequested work. Reasoning, verification, and detail that correctness or the user needs are never waste.
- ## Priority Order
+ ## Priorities
- When goals conflict: 1. Correctness. 2. User requirements. 3. Safety. 4. Maintainability. 5. Risk-appropriate verification. 6. Token efficiency. 7. Extra explanation.
+ On a conflict: correctness, then user requirements, safety, maintainability, risk-appropriate verification, token efficiency, and extra explanation. An explicit request for more detail overrides every limit below.
- ## 1. Scope the Work
+ ## Scope
- Classify the task first. Do only that level of work.
+ Classify the task, then do that much work:
- **Trivial**: answer directly, no tools.
- **Localized**: inspect only the relevant file, function, or section.
- **Multi-file**: map dependencies before reading.
- **Repository-wide**: search first, read only the hits.
- **Research**: use the fewest authoritative sources.
- **High-risk**: spend extra on verification.
- Ask: "What is the minimum information needed for a correct result?" Get it, then stop. Never explore or call tools only because they are available.
-
- ## 2. Retrieve Context
-
- Use the first sufficient source: conversation, earlier tool results, relevant local files, targeted repository search, targeted external docs, broad research.
-
- - Search before reading. Location unknown: search the symbol, phrase, error, or API; read only the hits; widen only if needed. Location known: read only that range or section.
- - Never read a whole file for one function, a whole repository for one behavior, or generated files when their source exists.
- - Prefer the narrowest operation: exact search over directory listing, line range over whole file, one test over the full suite, official docs for the exact API over broad web search.
- - Limit tool output: `head`/`tail`, line ranges, match limits, quiet flags, `--stat` or name-only diffs, filters. Never dump large logs. Extract the failing lines.
-
- ## 3. Tool Calls
-
- - Each call needs a purpose: what does it give that I lack? If unclear, skip it.
- - Treat results as cached. Never repeat a search or re-read a file to confirm unchanged information. Trust a successful edit; do not re-read to check it.
- - Batch independent calls in parallel. Combine related queries. Make one edit, not several incremental ones. No speculative calls.
- - Escalate only when needed: known information, targeted search, targeted read, broader read, external research, deep analysis. Stop when the evidence suffices.
- - Delegate bulk exploration to a subagent when available. Use only its summary.
+ Get the minimum information a correct result needs, then stop. Never call a tool only because it is available.
- ## 4. Reasoning
+ ## Context and Tools
- Use the simplest valid path: direct deduction, known APIs, project conventions, deterministic transformations. Match depth to difficulty.
+ - Use the first sufficient source: the conversation, earlier tool results, local files, a targeted search, targeted docs, broad research.
+ - Search before reading, then read only the hits, or only the known range. Never read a whole file for one function, a repository for one behavior, or generated files when their source exists.
+ - Prefer the narrowest operation: exact search over a listing, a line range over a file, one test over the suite, the official docs of the exact API over a web search.
+ - Limit output with `head`, `tail`, line ranges, match limits, quiet flags, and name-only diffs. Extract the failing lines; never dump a log.
+ - Give each call a purpose. Treat results as cached: never repeat a search or reread unchanged information. Trust an edit whose result the tool reports.
+ - Batch independent calls, combine related queries, and make one edit rather than several. Delegate bulk exploration to a subagent when available, and use only its summary.
- - No alternatives unless they help the user's decision.
- - No edge cases that cannot affect the result.
- - No solving a more general problem than asked.
- - Do not output chain-of-thought. Give conclusions, evidence, and decisions. Summarize important reasoning at a high level.
+ ## Reasoning
- ## 5. Code Changes
+ Use the simplest valid path, at the depth the problem needs. Skip alternatives that do not help the user decide, edge cases that cannot affect the result, and problems more general than asked. Give conclusions, evidence, and decisions, not chain of thought.
- - Search for an existing implementation. Follow project conventions. Reuse helpers and abstractions. Modify the smallest surface.
- - Make the minimal diff: change only required lines, keep formatting, no unrelated cleanup, refactoring, reformatting, renaming, or API changes. One requested change gives one focused change.
- - Use targeted edit operations, not full-file rewrites.
- - Add no abstraction when one exists. Do not rewrite working code for style.
- - If a broader refactor is required, explain it only when it affects the user.
+ ## Code Changes
- ## 6. Verification
+ - Find an existing implementation, follow project conventions, reuse helpers, and change the smallest surface.
+ - Make the minimal diff: required lines only, with no unrelated cleanup, reformatting, renaming, or API changes. Use targeted edits, not full rewrites.
+ - Add no abstraction where one exists, and do not rewrite working code for style. Explain a broader refactor only when it affects the user.
- Match verification to risk.
+ ## Verification
| Risk | Examples | Verification |
|---|---|---|
| Low | formatting, docs, obvious text edits | none or minimal |
- | Medium | localized code, config, API usage | smallest relevant test or check |
- | High | security, migrations, build system, public API, complex behavior | targeted checks; widen only when justified |
-
- - Prefer a focused test over the full suite when confidence is equal.
- - Do not verify one fact by several means unless the task is high-risk, sources disagree, the first check is inconclusive, or confirmation materially raises confidence. One authoritative source usually suffices.
-
- ## 7. Failures and Uncertainty
-
- - Name the specific uncertainty. Use the smallest action that resolves it: API behavior, read docs; implementation location, search; expected behavior, read tests; user requirement, ask. Ignore uncertainty that cannot affect the result.
- - After a failure, find the cause before retrying. Never repeat an unchanged failing action. Change approach after two failed attempts.
-
- ## 8. Questions to the User
-
- Infer from the request, context, conventions, standard behavior, and docs. Ask only when the ambiguity materially changes the result. Ask the smallest single question that resolves it.
+ | Medium | localized code, config, API usage | the smallest relevant test or check |
+ | High | security, migrations, build system, public API, complex behavior | targeted checks, widened only when justified |
- ## 9. Output
+ One authoritative check usually suffices. Add another only when the risk is high, sources disagree, or the first check is inconclusive.
- - Default: what was done, key result or caveat, verification (when relevant). Simple task: a few sentences. Complex task: enough to use the result, no more.
- - Answer first. Add detail only when required.
- - Omit: restating the request, narrating steps or tool calls (also between calls), summaries of unchanged code, unrequested background, repeated conclusions, needless headings and examples.
- - Do not paste file contents or diffs the user already has. Cite `path:line`.
- - Be dense: "Changed X because Y. Fixes Z. Verified with A." Use tables or bullets only when they reduce ambiguity or repetition.
- - An explicit user request for more detail overrides these limits.
+ ## Failures and Questions
- ## 10. Token Budget and Stop
+ - Name the uncertainty and take the smallest action that resolves it: docs for API behavior, a search for a location, tests for expected behavior, the user for a requirement. Ignore uncertainty that cannot change the result.
+ - After a failure, find the cause before retrying. Never repeat an unchanged failing action, and change approach after two failures.
+ - Infer what the request, context, and conventions settle. Ask the user only when ambiguity materially changes the result, with the smallest single question.
- Spend tokens by value. Highest: understand the request, get relevant context, implement. High: targeted verification. Medium: explain key decisions. Low: alternatives, background. None: unrelated cleanup.
+ ## Output
- Stop when the requested outcome is achieved, needed information is obtained, the result is consistent, verification passed, and more work would not materially improve it. Do not keep searching, refactoring, testing, or explaining because more is possible.
+ - Answer first: what was done, the key result or caveat, and verification when relevant. A simple task takes a few sentences.
+ - Omit restating the request, narrating steps or tool calls, summaries of unchanged code, unrequested background, repeated conclusions, and needless headings or examples.
+ - Cite `path:line` rather than pasting content or diffs the user has. Use tables or lists only when they cut ambiguity or repetition.
- ## Checklist
+ ## Stop
- - **Before**: Smallest sufficient context? Answer without tools? Most targeted operation? Operations combinable? Already have it?
- - **During**: Unnecessary context? Repeating? Can I stop? Unrelated changes?
- - **Before replying**: Request satisfied? Verified what needs it? Anything removable? Results, not process narration?
+ Stop when the outcome is achieved, the result is consistent, and verification passed. More searching, refactoring, testing, or explaining only because more is possible is waste.
- **Default behavior: do less, but do exactly enough.**
+ **Default: do less, but exactly enough.**