scip-query AGENTS.md

scip-query

This repository uses scip-query as its primary code exploration surface.

scip-query separates two responsibilities: the agent decides what repository fact it needs, while the tool locates exact referents and reports compiler, runtime, data, state, temporal, contract, identity, ownership, and dependency evidence without guessing task relevance. The ordinary loop is locate an exact root, project explicitly chosen relationships, read behavior only for a named remaining gap, then stop when the requested claims are established.

• Use scip-query for repository exploration, including literal search and exact source reads. Native tools are for applying edits, running checks, binary content, or a specific unsupported gap that scip-query has explicitly reported—not a parallel exploration workflow.
• Before exploring, state the few material repository facts the answer depends on. Include behavior-changing predicates, authorization checks, data reshaping, hard bounds, runtime crossings, durable state changes, emitted notifications, returned values, relevant sibling outcomes, and externally visible ordering only when the request depends on them.
• For end-to-end explanations, the installed scip-query skill maintains a private evidence ledger and audits the final answer as part of the same exploration workflow.
• scip-query search <exact-text> — Where does this exact text occur in current project text, and which aligned compiler symbol owns each line? Requires: One exact text literal or deliberately bounded regular expression; insert -- before a literal that starts with a dash.
• scip-query outline <file> — What symbols and nesting exist in this file? Requires: One exact current project file path.
• scip-query entrypoints [text] — Which detected external roots or entry-surface candidates match this text? Requires: Optional exact text to filter candidates; otherwise the current indexed repository.
• scip-query evidence — Which exact execution, runtime, data, state, temporal, contract, identity, ownership, or dependency relationships surround these referents? Which related source must be read only when graph evidence leaves a named implementation gap? Requires: One or more exact symbol, file:line, or literal roots plus explicit family, direction, depth, and output bound.
• scip-query inspect — Which related source units across several known text, symbol, or location anchors should be read together? Requires: One or more exact text, symbol, or file:line selectors naming the unresolved behavior.
• scip-query code <selectors...> — What exact source defines these symbols, ranges, or file surfaces? Requires: One or more exact symbols, file:line ranges, or file paths.
• Choose graph controls explicitly: execution incoming — Who can call or reach this?; execution outgoing — What can this call or reach?; dataflow incoming — Where can this value come from?; dataflow outgoing — Where can this value go?; runtime both — Which producer and consumer rendezvous?; state both — What resource is observed or changed?; temporal both — What occurs before or after this?; contract both — What interface constrains this?; identity both — Are these observations the same entity?; ownership both — What contains or owns this?; dependencies outgoing — What does this statically rely on?. The CLI does not infer them from English intent.
• Calibration: exact is directly observed; derived is deterministically computed; candidate needs confirmation; mixed discloses its constituents; unknown cannot support a stronger claim. Read coverage and recovery before making absence claims.
• The controls above are complete for ordinary exploration. Run scip-query capabilities --matrix only when a named claim depends on uncertain provider support; do not run it for routine orientation.
• Any exact symbol or file:line returned by a locator is immediately usable as a graph root. There is no required anchor-discovery phase and locator ordering never proves task relevance. For an end-to-end question, include the initiating owner as a root or request incoming execution capable of exposing it; do not assume a core type is the ingress. Locate independent roots together when the question already implies several participants.
• A materialized evidence projection requires repeated --symbol, --at, or --search selectors plus one or more repeated --edge <family> flags, explicit --direction incoming|outgoing|both, --depth <n>, and --max-edges <n>. The agent chooses the relationships capable of establishing its claim; the CLI resolves identity, direction, evidence strength, provider support, and coverage. Use optional exact --subtype <subtype> and --connecting only when the selected roots themselves must be connected. Never request complete, all, or every family merely to discover what exists; use --inventory-only when only counts can determine the next bounded projection.
• Treat execution calls and exact runtime handoffs as executable reachability. Dataflow, state, temporal, contract, identity, ownership, and dependency edges say what a path carries, changes, orders, constrains, identifies, contains, or relies on; they do not become call claims. Treat exact edges as facts only within their stated coverage and candidate edges as leads requiring source confirmation.
• Read every packet as a coverage contract. accounted means the requested bounded projection reports every omission; bounded means requested edges were placed in stable recoverable folds by the output budget; incomplete means a selector or provider could not be resolved. None proves the user task complete, and missing output is no evidence of absence.
• Prefer batched locators, projections, and gap reads. Query count measures exploration efficiency; it never makes a known recoverable material fact optional. Before drilling down, name the still-missing fact. Expand only a printed fold or exact adjacent identity that can establish it; batch independent roots and gaps instead of shuttling between abstraction levels, and repeat only while a named fact remains unresolved.
• Use scip-query inspect --symbol <symbol> --symbol <symbol> --at <file:line> --view behavior for several named behavioral gaps. Connected behavior is already source evidence; do not reread lines it rendered. Use scip-query code <symbol-or-range> only when exact implementation syntax can change the decision. Do not replace these reads with rg, grep, sed, or nl.
• For a multi-step mutation, preserve later compaction, rollback, and cleanup. For every event, log, or outbox write, preserve its operation and record identity. For coordination, state the lock scope and which checks and writes occur inside it. State whether interruption is prevented, atomic, rolled back, or repaired later. Resolve exact constant values when they can change the answer.
• For a tiered policy or dispatcher, preserve the precedence of its tiers and the exact scope of every bypass; never imply that a later bypass can skip an earlier hard rejection unless the rendered condition proves it.
• For a stateful owner, preserve its lifetime and sharing scope, including whether it is a singleton, shared registry, per-session instance, or per-invocation value.
• Use scip-query diff-impact to map changed symbols and downstream consumers after a nontrivial edit.
• Use scip-query architecture to inspect explicit structural rules.
• Use scip-query health to find React, Vue, duplication, complexity, drift, and cleanup candidates.
• Before claiming a complete relationship set or an absence, inspect coverage and use --full only when complete coverage can change the decision. A bounded or unsupported result cannot establish that no caller, route, branch, poller, or consumer exists.
• Before claiming what every callsite passes, read the trace or evidence claim-support section. Only an eligible callsite-argument claim is backed by complete syntactic invocations; bounded context is not proof.
• Prefer human output for agent reading. If a model-facing consumer genuinely needs JSON, add --json --agent-output; add --result-only only when the common envelope is unnecessary, and drain every emitted cursor before interpreting the result. Never send raw --json output through a model-facing terminal or tool. When a program needs the exhaustive machine payload, use --json --json-output <path> and inspect that file programmatically instead of injecting its complete contents into model context.
• Never rerun a successful human command as JSON. Before each drilldown, name the still-unanswered fact and check whether an earlier packet already establishes it; if so, update the ledger or draft without another query. Stop when no unanswered fact remains because every additional reasoning step pays again for the accumulated context.
• Before answering, compare the draft to selected statement-complete behavior. Preserve every material behavior-changing predicate, returned default, separately merged field, cache invalidation, and cleanup effect. Do not collapse fields with different operations into a generic summary, and do not re-query evidence already in context.
• With an explicit SCIP_QUERY_SESSION, a complete source unit, a byte-identical exact subset of a prior exact source read, or a graph unit/edge may be replaced by a visible receipt from the same index generation. Preview coverage never suppresses an exact unit; changed bytes, changed graph content, a new generation, or --reemit force full evidence.
• An emitted Continue exactly: command is a cursor: a next-page read from one immutable rendered result. It is required transport, not optional evidence expansion. Run it unchanged and repeat until no continuation remains before interpreting that command's complete result. Do not rerun the original query or alter cursor flags. Continuation reads saved output without repository preparation, reindexing, or watcher startup. Printed recovery and expansion commands are different: run those only when their omitted evidence matters.
• When architecture rules are configured and clean, setup installs one checkout-local Stop hook. It checks architecture only after indexed source changes.
• Commit relevant .scipquery/suppressions/*.json records with the change. Do not commit local agent-tool settings.