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
Bound discovery, reuse validated state, and reduce model-visible context without lowering required quality, safety, or verification. Token reduction is a measured downstream result, not an assumption. Never add work solely to demonstrate efficiency.
Version: 2.5 Updated: 18 August 2026 Licence:CC BY 4.0
Precedence and conflicts
Platform, system, developer, project, security, legal, and domain-specific instructions override this package. Efficiency rules never weaken a mandatory control or acceptance criterion. When rules conflict, follow the higher-priority rule, perform the required work, and record the reason the normal efficiency target was exceeded.
Targeted edits
When the user gives a path, location, identifier, or exact phrase:
Do not inventory or recursively list the workspace.
Search the exact phrase only in the smallest likely canonical-source root; cap the command output.
Inspect the matched range and direct dependencies, then edit the canonical source.
Do not read an existing builder, manifest, inventory, generated output, or unrelated source unless locating the target, making the edit, or resolving a failed required check needs it.
Run the existing builder, then the canonical validator once, then inspect the affected output once at the fidelity required.
Stop when the request's acceptance criteria pass. Do not repeat successful checks or run overlapping diagnostics.
For a simple targeted edit, aim for no more than six model-visible operational results after mandatory instruction reads: locate/inspect, edit, build, validate, affected-output check, and at most one focused recovery. This is a target budget, not a hard safety limit. Exceed it when a named failure, ambiguity, shared dependency, higher-priority instruction, or mandatory check requires more work, and state the reason.
Count each result returned to model context, not each shell subcommand hidden inside one local operation. Report shell commands, tool calls, and model-visible results separately when benchmarking; they are not interchangeable.
When a semantic value changes, update its routing term or let the existing builder regenerate companion state. Prefer one deterministic validator over several manual checks.
Output bounds
Every discovery command must enforce its limit before execution: at most 100 lines or 12,000 characters by default, never above 20,000 characters unless full content is explicitly required.
Never use Get-ChildItem -Recurse, find, a workspace tree, or an equivalent recursive listing for a named target.
Never print a large file in full. Search first, then read only the required line, page, section, or object range.
Recursive text search must name the smallest root and text types, respect ignores, exclude irrelevant dependencies/builds/caches/renders/binaries, and cap matches.
If a tool cannot cap output, keep it local and return only counts, filenames, a diff, failures, or the required excerpt.
If a limit is reached, narrow the query. Never raise the cap or repeat the broad command.
Repeated large sources
For repeated PDF, Office, image, audio, or video work, reuse a validated Markdown/text extraction or compact index when its source fingerprint and settings still match. Search that layer, then inspect only required original pages or objects. For a one-time task, direct inspection may be cheaper than creating a cache.
Derived text inherits the source's sensitivity. Store it only in an authorized location with appropriate access controls, encryption where required, a defined retention period, and a deletion path. Keep confidential or restricted extractions, OCR, manifests, and indexes out of public repositories and shared caches. Redact before sharing, and delete or invalidate derived state when authorization ends or the source lifecycle requires it.
Optional references
Do not load another file from this package for a simple targeted edit. Use one only when this core is insufficient: artifact-revision-workflow.md for complex revisions, document-extraction-adapters.md for extraction design, artifact-manifest-template.yaml for justified new companion state, or efficiency-measurement-checklist.md and validation-protocol.md for a controlled study.
A saving requires fewer measured model-input tokens and equivalent required quality in a comparable test.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Read this file when modifying an existing artifact, maintaining its inventory, or choosing the required verification scope. The core rules remain in agent-instructions.md.
Canonical source and revision set
Keep a maintainable canonical source when an artifact is likely to receive future revisions. Examples include structured content plus a presentation builder, Markdown or HTML plus a PDF generator, source components plus website content data, and workbook data plus formulas and charts.
Modify the canonical source, regenerate the output, and verify the result. Record the relationship between source and output. Here, a builder means the project's existing canonical generation path, such as its established script, application, or export workflow. Do not invent a builder solely to satisfy this procedure; if none exists, edit with the safest native workflow and record how the output was produced.
Treat these affected items as one revision set:
canonical source;
generated output;
artifact manifest and inventory;
dependency and impact map;
asset registry;
extraction or analysis cache;
fingerprints and change record.
Update affected members together. Preserve the last valid revision set and do not present a partially synchronized set as complete.
For a semantic change, record the old and new routing terms in the revision set. Validation must fail if the canonical value changed but related search phrases, aliases, inventory text, or dependency labels still route only by the superseded value.
Separate content from presentation and behaviour
Keep audience-facing text, data, asset references, and citations separate from layout, styling, animation, formulas, and export logic when practical. A wording change should not require reinterpretation of the complete design implementation.
Use deterministic parsers, indexes, and diffs to locate known text, symbols, cells, fields, pages, or objects. An unchanged item may still be affected by a changed shared dependency, so check the impact map before excluding it.
Bounded discovery
The context limits in agent-instructions.md apply to every discovery command. A later recursive search is not exempt merely because an earlier file listing was bounded.
Use this sequence:
Search the manifest or inventory for a stable identifier or exact phrase.
If needed, list matching filenames or return match counts before content.
Search only the likely roots and text file types.
Exclude dependencies, generated files, caches, renders, and binaries on the same command.
Return only bounded matches with short context.
Inspect the matched source range and direct dependencies.
Stop discovery after the target is unique and dependencies are resolved.
If the candidate result may still be large, write it to a temporary local file and return only its count, candidate filenames, or the required slice. Do not combine unrelated broad searches into one large tool result.
Inventory rules
An inventory routes the agent to likely locations. It does not replace inspection of the current source.
Create an inventory during initial production when the relevant information is already available. Keep it cheaper to read than the artifact.
Record only useful fields:
artifact path, type, fingerprint, size, modification time, and item count;
one compact entry per page, slide, sheet, section, component, or media item;
stable identifiers and unique searchable phrases;
purpose, visible content, assets, citations, and dependencies;
shared or inherited elements;
last-updated, last-verified, and confidence state.
Do not embed media, binary data, full OCR, or verbose object trees. For large artifacts, use a hierarchy:
artifact summary
-> section index
-> item range
-> detailed item entry
Inventory-first routing:
Compare the recorded fingerprint with the current artifact.
If it matches, search the inventory or manifest.
Inspect the current matched item in the source.
Make and verify the smallest safe change.
Update the output and affected companion state.
If the fingerprint differs, mark the inventory stale. Do not use its locations as current evidence.
Use artifact-manifest-template.yaml when machine-readable state is justified. Generate any human-readable inventory from that state instead of maintaining two independent copies.
When companion state is justified
Add inventories, manifests, caches, or dependency maps when one or more conditions apply:
the artifact has many independently editable items;
locating content is expensive;
it contains media, OCR, tables, formulas, or shared dependencies;
multiple revisions, users, or agents are expected;
rediscovery or rebuilding would be costly;
auditability or reproducibility matters.
For a small, disposable, one-time output, skip companion files when their maintenance cost is likely to exceed their reuse value.
Risk and verification direction
Risk
Typical change
Verification direction
Low
Exact typo or isolated value
Target, context, affected output, and integrity check
Medium
Image, chart, formula, layout, or bounded section
Target, dependencies, and representative affected output
High
Theme, shared data, repeated component, or structural rewrite
Full impact map and broad affected-output verification
Critical
Regulated, signed, safety-sensitive, or externally consequential output
Required evidence, approvals, controls, and domain checks
Risk classification never overrides mandatory checks.
Use these confidence states:
verified: checked against the current artifact;
generated: produced from the canonical source but not visually confirmed;
partial: known fields are omitted;
stale: the artifact no longer matches the recorded fingerprint;
unknown: extraction, parsing, OCR, or mapping was unreliable.
Record material omissions. Do not present inferred relationships, OCR, or generated descriptions as verified facts.
Format-specific checks
Code: change one function
Locate the named symbol with a code index or exact search.
Inspect the function, callers, types, and focused tests.
Modify the smallest relevant source region.
Run focused tests, then required broader checks.
Inspect more of the repository only when dependencies or failures point there.
Presentation: change one sentence
Validate the deck fingerprint and search the slide inventory.
Inspect the current text object on the matched slide.
Change only that object or its canonical content value.
Preserve layout, typography, media, animation, notes, and citations.
Render the affected slide and check wrapping, clipping, overlap, and visual balance.
Complete any mandatory deck-wide integrity or visual checks.
Update the inventory and fingerprint.
Also verify that the new sentence is represented in slide routing metadata and that the old sentence is absent unless deliberately retained as an alias.
If the change affects a master, layout, footer, logo, repeated phrase, or shared asset, verify every affected consumer.
PDF or another extraction-heavy source
Read document-extraction-adapters.md. Use its cached-extraction and page-verification rules. Prefer modifying the canonical editable source and regenerating the exported document when that source exists.
Spreadsheet: change one formula
Locate the named cell or table field.
Inspect precedents, dependants, validation rules, and affected charts.
Change the formula at its correct source.
Recalculate and verify expected values and error states.
Inspect other sheets only when dependency tracing requires it.
Website or application: change one component
Locate the component and its content, styles, callers, tests, and shared dependencies.
Modify the narrowest canonical source.
Run focused automated checks.
Verify the affected route and relevant viewport or interaction states.
Expand to other routes only when shared state or a failed check requires it.
Image, audio, or video
Use metadata, transcripts, shot lists, asset registries, or fingerprints to locate the target. Do not resend unchanged binary content to the model when a valid derived representation exists. Inspect the original media at the fidelity needed to verify the requested change.
Completion conditions
The requested target and acceptance criteria were clear.
Discovery started at the narrowest safe scope.
The current target was verified before modification.
Unaffected work was preserved.
Shared dependencies were included in the impact check.
Required targeted and global checks passed.
Affected companion state was updated or marked stale.
Sensitive information stayed out of public or low-trust files.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Read this file when a PDF, DOCX, PPTX, XLSX, image, audio file, or another expensive source will be queried or revised repeatedly.
Extraction creates a reusable text and structure layer. The original artifact remains authoritative for appearance, signatures, form state, image meaning, and any property the extraction cannot prove.
Reuse before extraction
Calculate the source fingerprint.
Look for a cached extraction and manifest.
Reuse the extraction only when the source fingerprint, relevant dependencies, extractor version, and settings match.
If any required input differs, mark the affected extraction stale and regenerate only what changed.
Do not extract and send the complete source to the model again for every request.
Do not automatically load a complete cached extraction into model context. Search its index first, then read only the relevant section or page range. Keep full extraction output local when a bounded excerpt, table, diff, or exception list is sufficient.
Default extraction workflow
Identify the source type and whether it has selectable text, complex layout, tables, formulas, embedded media, or scanned pages.
Choose the cheapest suitable local extractor.
Produce Markdown for model-facing text and structured JSON or a manifest when page or object provenance is required.
Preserve page, slide, sheet, section, or media boundaries when the extractor supports them.
Run the quality gates below.
Cache passing output with its manifest.
If a named quality gate fails, record the failure and try one stronger fallback.
Do not run every extractor by default.
Before returning extracted text to the model, apply the core context budget. When the needed excerpt exceeds it, split by verified boundaries and process only the required chunks; aggregate locally where deterministic counting, hashing, filtering, or comparison can answer the question.
For mixed supported formats, install the specific extras required by the workflow instead of [all] when practical.
MarkItDown output is intended for text analysis rather than high-fidelity visual reproduction. Standard PDF conversion may not provide reliable page markers. Verify page mapping or create a separate page index; never assign extracted text to a page without evidence.
For local-only applications, prefer a narrow method such as convert_local() or convert_stream() over a permissive converter that can also access remote resources.
PDF companion layer
When a PDF will be used more than once, create a page-mapped Markdown companion during the first inspection when practical.
Record the PDF fingerprint.
Extract selectable text and use OCR only where needed.
Record figures, forms, signatures, and uncertain OCR instead of treating Markdown as complete.
Store the source fingerprint, extractor, version, settings, extraction date, output fingerprint, page-mapping state, and OCR state.
Use the Markdown to search and route later requests while the source remains unchanged.
Open or render only the relevant PDF pages when layout, images, forms, tables, signatures, or uncertain extraction matter.
For a short, one-time PDF, skip the companion layer when creating and validating it would cost more than inspecting the document directly.
Quality gates
Run the checks that apply to the source:
Gate
Pass condition
Source match
Recorded fingerprint equals the current source
Coverage
Expected pages or items contain plausible extracted content
Boundary mapping
Required page, slide, sheet, or section identifiers are preserved and verified
Reading order
Representative multi-column or structured pages read in the correct order
Tables
Required rows, columns, headers, and merged cells remain usable
Formulas and symbols
Required notation remains intelligible and complete
OCR
Scanned regions are present and uncertain text is labelled
Assets
Important figures, captions, and asset references are represented
Security
Output contains no newly exposed secrets or unnecessary personal data
A failed gate must name the failed property. Do not escalate because one output merely looks less polished.
Controlled fallback
Use one fallback at a time:
default extractor
-> quality gates pass -> cache and use
-> named gate fails
-> record failure
-> choose one extractor suited to that failure
-> rerun affected extraction
-> repeat the failed gate and required integrity checks
Cross-validation with another extractor is justified when the task requires high confidence and a deterministic check cannot establish correctness. Do not return both full outputs to the model; return the differences and relevant excerpts.
OCR, models, and cloud services
Use OCR only when the native text layer is missing or unreliable.
Prefer page- or region-level OCR over processing the complete document again.
Cache OCR by source and region fingerprint.
Record the OCR engine, model, language, settings, and confidence state.
Treat LLM vision calls as model usage, not free preprocessing.
Do not send sensitive documents to a model, plugin, hosted API, or cloud extractor without authorization for that destination.
Record whether processing was local or external and whether the external call was billable.
Sensitive derived-state lifecycle
Derived text, OCR, indexes, embeddings, manifests, thumbnails, and analysis inherit the source's sensitivity unless an authorized classification process says otherwise.
Store derived state only in an approved location; record whether it is local, shared, or external.
Apply least-privilege access and encryption when the source classification requires them.
Keep confidential or restricted derived files out of public repositories, ordinary build artifacts, and shared caches.
Define retention or review dates and a deletion owner for reusable state.
Redact or regenerate a sanitized derivative before sharing outside the authorized audience.
When a source is deleted, authorization ends, or retention expires, delete or invalidate its derived state and record the action.
A fingerprint mismatch invalidates reuse but does not itself delete sensitive content; lifecycle policy decides deletion.
Manifest and reporting
Use artifact-manifest-template.yaml as the companion-state starting point. Remove fields that the workflow does not need.
At completion, report:
the source and derived files;
whether an existing extraction was reused;
the extractor, version, and relevant settings;
quality gates run and any failure;
fallback used and why;
pages or items inspected in the original artifact;
confidence and limitations.
Do not claim a universal PDF or conversion token multiplier. Cost varies with extraction, OCR, images, tables, rendering, returned context, and the model used.
Read this file when testing or claiming that a workflow reduces tokens or other costs.
Comparable test contract
Use the same:
user request and acceptance criteria;
source artifact version;
model and relevant settings;
tool access and permissions;
required safety and quality checks;
expected output quality.
Record any unavoidable difference. Do not compare a fully verified baseline with a lightly checked alternative.
Repeated crossover design
For a performance claim, use at least 5-10 runs per condition. Alternate and order-balance the conditions, for example baseline -> candidate -> candidate -> baseline, then repeat with fresh equivalent fixtures. Record warm/cold cache state and platform/runtime version for every run. Do not reuse a modified artifact as the next run's input.
Report median, interquartile range, minimum, maximum, success rate, and quality-failure count for each condition. Separate cached and non-cached model input. A single run may be labelled exploratory or MVP evidence, but not generalized proof.
Before-and-after evidence
Metric
Baseline
Efficient workflow
Evidence source
Reported input tokens
Cached input tokens
Non-cached input tokens
Reported output tokens
Tool-output characters returned to the model
Largest single tool result in characters
Tool results exceeding the package ceiling
Items semantically inspected
Items visually inspected during iteration
Full-artifact extractions
Cache hits
Cache invalidations
Tool calls
Shell commands
Model-visible operational results
Elapsed time
External API or model calls
Estimated external cost
Required quality checks passed
Unrelated changes detected
If direct token counts are unavailable, record unavailable. Use the remaining fields as labelled proxies and do not turn them into an invented token percentage.
Fewer tool calls do not prove fewer tokens. Local computation, model context, external API cost, elapsed time, and human review are separate measures.
Quality equivalence
Confirm that both workflows:
satisfy the same request;
preserve the same unaffected work;
pass the same mandatory checks;
meet the same visual, semantic, functional, and safety standard;
disclose comparable limitations.
Count an efficiency improvement only when the required quality remains equivalent.
Regression gates
A candidate revision fails the token-efficiency objective when any of these occur without a documented mandatory reason:
one tool result exceeds the package's 20,000-character discovery ceiling;
a recursive search omits relevant scope, type, and high-volume-directory controls;
discovery continues after the unique target and direct dependencies are known;
full extracted content is loaded when a bounded indexed excerpt would suffice;
visible or semantic content changes while routing metadata retains only the old value;
the efficient condition uses more model-input tokens than the comparable baseline;
quality or mandatory verification is weaker than the baseline.
Treat a failed run as diagnostic evidence, not as a saving. Correct the identified mechanism and rerun the same task before expanding the benchmark set.
Instruction-budget audit
Measure the instructions that are loaded for every task separately from references loaded on demand.
Instruction layer
Files
Lines
Estimated or measured tokens
Load condition
Always loaded
Every task
Scope specific
Matching directory or artifact
Procedure reference
Matching task only
Generated companion state
Relevant artifact only
Review any always-loaded rule that applies only to one format or task. Move it to a routed reference unless it is required for safety or universal behaviour.
Do not enforce a universal line or token limit. Models and agent platforms load instructions differently. Establish limits from measured tasks and revise them when the platform changes.
The package's tool-output ceiling is a conservative operational default, not a claim about a model's context capacity. Change it only with measured evidence and record the tested value.
Drift and conflict audit
Each rule has one canonical owner file.
The core routes to references instead of repeating their procedures.
A reference does not redefine instruction precedence.
Format-specific checks add to, rather than weaken, mandatory core checks.
Links and file names resolve.
Cached state has a current fingerprint.
Deprecated rules are removed instead of kept beside replacements.
Examples are labelled as examples rather than universal requirements.
Completion statement
Report:
what was compared;
measured token counts or their absence;
proxy evidence used;
required checks passed;
quality differences or limitations;
whether the result supports a token-saving claim.
Attach or link the run records, prompts, instruction snapshot, sanitized fixture, scripts, raw accounting trace, tool transcript, environment description, outputs, and comparison hashes. Use validation-protocol.md for the bundle contract.
This document records a reported one-run exploratory result in which the Token-Efficient Agent Instructions reduced measured model-input tokens while preserving the required output quality.
It is evidence for one task, model, artifact, and run. It is not independently reproducible from this package and is not a universal performance claim.
Evidence status
The package retains the reported metrics and quality checks, but it does not include the original fixture, exact baseline and experimental prompts, complete instruction-loading state, raw accounting trace, full command transcript, validator and rendering scripts, environment lockfile, generated outputs, or comparison hashes.
Accordingly, this result is exploratory rather than independently controlled. Another person cannot yet rerun or independently audit it. Future validation must follow validation-protocol.md and publish a sanitized evidence bundle.
Test contract
Task: On slide 2 of a 12-slide PowerPoint, replace one exact sentence containing four hours with the equivalent sentence containing six hours.
Preserve: All other audience-facing content, layout, media, notes, metadata, and behaviour.
Baseline: Same request and artifact without the Token-Efficient Agent Instructions.
Efficient condition: Same request and artifact with version 2.4 loaded locally.
Model:gpt-5.6-terra.
Permissions and runtime: Identical for both conditions.
Required checks: Exact text replacement, synchronized companion state, canonical validation, slide rendering, and visual inspection of the affected slide.
Before-and-after results
Metric
Baseline
Version 2.4
Change
Input tokens
743,910
557,679
-186,231 (-25.03%)
Cached input tokens
672,512
516,864
-155,648 (-23.14%)
Non-cached input tokens
71,398
40,815
-30,583 (-42.83%)
Output tokens
4,139
4,279
+140 (+3.38%)
Reasoning output tokens
1,406
1,631
+225 (+16.00%)
Tool-output characters
620,572
58,648
-561,924 (-90.55%)
Largest tool result
505,616
15,595
-490,021 (-96.92%)
Tool results above 20,000 characters
4
0
-4
Command calls
8
12
+4 (+50.00%)
Elapsed seconds
135.804
142.332
+6.528 (+4.81%)
Was output quality affected?
No quality reduction was detected in this test. Quality equivalence was an explicit pass condition, not an assumption based on the files looking similar.
Both conditions passed the same checks:
the requested new sentence appeared correctly on slide 2;
the old full sentence was absent;
canonical source and manifest routing terms were synchronized to six hours;
both strengthened canonical validators returned VALID;
all 12 rendered slide PNGs were byte-identical between conditions;
slide 2 was visually inspected for clipping, overlap, and unexpected wrapping;
no unrelated audience-facing change was detected.
The PPTX archive hashes differed because regenerated Office files can contain package-level differences. The rendered slides, canonical semantic state, routing state, and required validator results were equivalent.
What improved
Version 2.4 reduced both total and non-cached model-input tokens. It also prevented the oversized discovery results that caused earlier versions to fail.
The main effective behaviours were:
using the named target instead of recursively inventorying the workspace;
bounding every discovery result before execution;
avoiding automatic loading of detailed reference files;
using the existing builder and canonical validator;
stopping after the required acceptance criteria passed.
Trade-offs
The efficient condition made more command calls and took slightly longer. This demonstrates that command count, elapsed time, tool-output size, cached input, and total model-input tokens are separate measures.
For this Gist, success means lower measured model-input tokens with equivalent required quality. Faster execution is desirable but is not used as a substitute for the token and quality gates.
Six-result target versus twelve commands
Version 2.4 described a six-call limit while this run recorded 12 command calls. The retained evidence does not include a call-by-call transcript, so it cannot establish which commands were mandatory reads, grouped local subcommands, operational results returned to the model, or recoveries. A post-hoc call table would be invented evidence.
Version 2.5 resolves the rule prospectively: aim for six model-visible operational results, permit named exceptions, and measure shell commands, tool calls, and model-visible results separately. This clarification does not retroactively make the v2.4 run compliant with a hard six-call rule.
Limitations and next evidence
This result covers one targeted PowerPoint sentence edit using one model and one run per condition. Agent behaviour, caching, platform versions, and artifact complexity can change the result.
Before claiming general effectiveness:
run an alternating, order-balanced crossover with at least 5-10 runs per condition;
report median, interquartile range, minimum, maximum, success rate, quality failures, and cached versus non-cached input;
test complex and shared PowerPoint changes;
test PDF question-and-revision workflows;
test code, spreadsheet, website, and document modifications;
require equivalent quality and mandatory verification in every comparison.
Until then, the supported claim is:
Version 2.4 reported a 25.03% input-token reduction in one exploratory PowerPoint modification run while passing the recorded quality checks and producing byte-identical rendered slides.
Bounded discovery, cached extraction, narrow modifications, and measured token use without lowering the required quality of the result.
The package's primary claim is context and tool-output discipline. Lower token use is a downstream outcome that must be demonstrated per workflow.
It applies to code, websites, presentations, PDFs, documents, spreadsheets, data, images, audio, video, and other revision-prone outputs.
Start here
Use agent-instructions.md as the only always-loaded agent instruction from this package.
For Codex, save that file as AGENTS.md or reference it from the applicable AGENTS.md. For another agent platform, place it in the platform's project instructions. Pasting a Gist link alone does not guarantee that an agent will read its files.
Keep the remaining files available for on-demand use:
Reproducible crossover benchmark contract and evidence-bundle requirements
Running or auditing repeated validation
Do not paste every file into every task. References are optional; do not load one merely because its topic matches the current file type.
Core objective and success test
This package improves context efficiency when it reduces avoidable model-visible context and tool output while preserving equivalent output quality, safety, and mandatory verification. A token-efficiency claim additionally requires lower measured model-input tokens in a comparable test. It is designed to control the largest avoidable costs:
oversized tool results entering model context;
broad repeated discovery after the target is already known;
rereading unchanged extraction-heavy sources;
rebuilding unchanged artifact regions;
stale companion state that makes later routing unreliable.
The default discovery budget is 100 lines and 12,000 characters, with a 20,000-character ceiling per tool result. Larger raw results stay outside model context and are reduced locally to counts, filenames, hashes, diffs, exceptions, or targeted excerpts.
Operating model
User request
-> classify scope
-> load only triggered guidance
-> locate with metadata, indexes, hashes, or exact search
-> inspect the current target and direct dependencies
-> make the smallest safe change
-> verify in proportion to impact
-> update affected companion state
For reusable source documents:
Source fingerprint
-> matching validated extraction exists? -> reuse it
-> no match -> run the cheapest suitable local extractor
-> run quality gates
-> pass -> cache output and manifest
-> fail -> record the failure and try one stronger fallback
What this package does not permit
Token efficiency does not permit skipped safety checks, ignored instructions, guessed source locations, unverified output, or lower-quality delivery. It narrows the working set until evidence requires expansion.
It also does not assume that fewer tool calls mean fewer model tokens. Measure the actual workflow when efficiency is a stated goal.
Measured corrections
A controlled PowerPoint sentence-edit test found that version 2.0 used 24.08% more input tokens than the no-Gist baseline. One recursive search returned 1,048,576 characters after failing to exclude node_modules, and the edited slide's routing phrase was left stale.
Version 2.1 added hard ceilings and cut tool-output characters in a fresh test, but still used 44.71% more input tokens because it triggered 29 command calls versus the baseline's 8. Automatically loading a detailed revision workflow and auditing compliance created more work.
Version 2.2 made references optional, but a fresh run still used 28.60% more input tokens after the agent ignored the generic bound and recursively printed 1,048,576 characters.
Version 2.3 replaces abstract guidance with a targeted-change fast path and explicit prohibitions against recursive workspace listing, large full-file reads, and duplicate diagnostics after the canonical validator passes. These corrections are not themselves proof of savings; repeat comparable tests and use median results before making a general claim.
Version 2.4 added a simple-edit call budget and stricter stopping rules. In one fresh run of the same PowerPoint task, it used 25.03% fewer input tokens and 90.55% fewer tool-output characters than the fresh baseline. Both validators passed, routing metadata matched, and all 12 rendered slides were byte-identical. The v2.4 run was 4.81% slower and recorded 12 command calls versus 8. Because the raw call transcript and complete rerunnable bundle were not retained here, the run cannot prove compliance with a six-call hard cap or support independent reproduction.
Version 2.5 renames the package around the mechanism actually demonstrated, changes six calls from a hard cap to a model-visible-result target, defines precedence, adds sensitive-cache lifecycle controls, and introduces a repeated alternating crossover protocol. The original v2.4 numbers remain legacy MVP evidence; they are not upgraded retroactively by the new protocol.
Use this protocol for future benchmark evidence. The legacy v2.4 record is incomplete and must not be treated as a rerunnable bundle.
Required bundle
Each benchmark case must contain:
an exact user request and acceptance criteria;
baseline and candidate instruction snapshots in their actual load order;
a sanitized, redistributable source fixture or a script that deterministically creates one;
validator, builder, renderer, and comparison scripts used by both conditions;
model, runtime, tool, operating-system, permission, and relevant configuration versions;
raw per-run token/accounting records and tool transcripts;
generated outputs or stable hashes when outputs cannot be distributed;
quality results, failures, exclusions, and operator interventions;
a completed copy of benchmark-run-template.yaml for every run.
The tool transcript must support a call-by-call accounting table:
ID
Purpose
Shell commands
Tool calls
Model-visible result?
Counted against target?
Exception or requirement
Evidence path
001
Do not reconstruct this table from memory after a run. If the raw transcript is unavailable, mark the accounting unverifiable.
Secrets, personal data, proprietary fixtures, and restricted derived state must not enter a public bundle. Sanitize or replace them with representative fixtures and record the substitution.
Experimental design
Freeze the task, fixture version, acceptance criteria, validators, and environment.
Run at least 5-10 trials per condition.
Use an order-balanced crossover, alternating which condition runs first in each pair.
Restore a pristine fixture before every trial.
Record cache state; do not silently mix warm and cold runs.
Apply the same verification and stopping conditions to both arms.
Preserve failed runs and explain exclusions before calculating summaries.
For each condition, report median, interquartile range, minimum, maximum, success rate, quality-failure count, cached input tokens, non-cached input tokens, total input tokens, output tokens, tool-output characters, shell commands, tool calls, model-visible operational results, and elapsed time.
Calculate percentage changes from the declared summary statistic, normally the median. Keep tokens, elapsed time, call counts, and external cost separate. A candidate passes only when required quality, safety, and verification are equivalent.
Claim levels
Exploratory: one or more runs without a complete rerunnable bundle.
Reproducible case result: complete bundle and repeated crossover for one task class.
Cross-domain evidence: reproducible case results across materially different artifact or code workflows.
Do not describe an exploratory result as independently reproduced or generally proven.
