Guide

Investigate an unfamiliar codebase

Build an answer from the repository’s own names, implementation, and tests. Start broadly enough to find the right area, then narrow each read to the question you are trying to resolve.

An unfamiliar repository makes it easy to recognise a plausible file and stop too soon. RepoQL helps separate orientation from verification: search identifies candidates, and focused reads establish what those candidates actually do.

State the behaviour you need to understand

Start with a concrete question, such as what happens when a session expires. Identify the repository involved and any evidence you already have: a request path, an error message, a test, or a symbol name. That gives the search a useful boundary without assuming the implementation.

Ask your agent to learn the local terminology with discover_vocabulary. It may find a refresh policy, an expiry check, or a differently named component. Carry those returned names into explore instead of inventing a likely class name.

Locate the implementation and its neighbours

Look for the code that makes the decision, the code that calls it, and tests that exercise it. A folder view can help explain the project layout, but directory names alone do not establish ownership or execution order.

Use structure views to identify declarations and entry points before reading full bodies. If search keeps returning a neighbouring feature, refine the question or scope. If it returns little, check whether the vocabulary or index readiness explains the gap.

Follow the decision through the code

Read the relevant function and the inputs that govern its branches. Then inspect its callers, registrations, and error handling. An indexed reference can help locate a connection; framework wiring and dynamic calls may require additional source reads.

For session expiry, distinguish who detects expiry, who decides whether renewal is allowed, and what the caller does when renewal fails. Those can live in different components. An explanation that covers only the successful path is incomplete.

Use history and tests for different questions

History can explain when a condition was introduced and what the author intended. The current implementation shows whether that condition still exists. Tests show specific expectations, while a reproduction can establish what happens with the inputs you care about.

Read relevant repository concepts too. They may explain a constraint that looks arbitrary, but compare their claims with the current evidence. A stored explanation can become stale.

Report the answer and its limits

Describe the behaviour in execution order and cite the code supporting each decision. Separate confirmed behaviour from an inference or an untested path. If the answer depends on configuration, language support, or an external service, state that dependency.

Useful commands

These orientation commands work in RepoQL.Core. Use the source directory and returned addresses from the repository you are investigating.

Terminal

rql read "file:///src/cloud/website/** => tree: folders" --token-budget 2000

Terminal

rql read "file:///src/** => concepts" --token-budget 1500

For a known symbol, add #symbol=Name to its file address. Append => history for commits or => references for indexed relationships. Addressing explains how these selections compose.

Further reference

In the installed manual: help:///tools/explore.md, help:///tools/read.md.