Serving the right context at the right cost
Ripwire’s ranked result is not yet the context an agent will use. The serving question is which signatures, bodies, relationships, and omissions deserve a place in a finite context window. This chapter explains the project’s detail ladder and budget behavior so a reader can choose a posture for orientation, conceptual search, exact symbol work, or body inspection without confusing a smaller response with a more complete one.
The distinction is easy to miss. Ranking decides what is relevant or important; serving decides how much of that evidence to materialize. A tool can rank the right function and still waste the agent’s attention by returning the whole surrounding file. It can also save bytes by cutting the answer so aggressively that the one fact needed to act disappears. Ripwire treats those as separate design problems.
The ladder is a serving policy
The task surface, --for, begins with the ranked symbols that match a description. For an exact, name-shaped request, the result can include the named symbol’s own body. That “own” matters: a same-named documentation section, type stub, or re-export from another file is not an acceptable substitute merely because it scored well. If the requested body does not fit the allowance, the honest outcome is to serve no body and expose the omission, rather than silently handing over a different definition.
A conceptual request has a different shape. When the task describes an idea rather than naming an identifier, ripwire’s compact route returns the ranked map with one-hop callee signatures and no body text. The map can show that a candidate calls parsing, caching, or serialization helpers without spending the full body budget on every candidate. The agent can then expand the one symbol whose relationship matters. An explicit body walk remains available when the agent values immediate detail over the compact default.
This is a progressive ladder:
- Ranked signatures identify the candidate, its location, and selected measurements.
- One-hop edges or callee signatures show the nearby relationship that made the candidate important.
- A selected body lets the agent inspect the implementation of the narrowed target.
- Impact and uses widen the question from “what is this?” to “what depends on it?”
- Source or compiler-grade evidence takes over when the map’s approximation is not adequate for the decision.
The order is not a rigid workflow for every task. It is a cost-aware default. An exact symbol that the agent must edit may justify jumping directly to the body. A broad conceptual question may be better answered by signatures and edges first. A targeted change with ambiguous callers may need impact or uses before the body is useful. The serving layer gives the agent choices while keeping the rank and its qualification visible.
The explicit detail control, --detail=N, makes the same policy predictable: full bodies for the top N ranked symbols and signatures for the remainder.