Guide

Investigate an unfamiliar codebase

Answer a question about code you have never seen, and know which parts of the answer the code proves. By the end you will have an answer that cites the exact code behind each claim and names anything still unconfirmed.

The example repository is a small auth service. The question is: “What happens to a user’s CLI tokens when they sign out?” Every command below was run against it from the repository root.

The route

Learn the local names. Turn your words into the words the code uses.
Find where the behaviour lives. Search with those names and your question.
Read the exact code. Pull the few declarations that decide the answer.
Check the answer. Test each link against the index and the team’s concepts.
Ask for an explanation, then check it. Optional: get a cited summary and verify its claims.

Learn the local names

You would search for “session”. This team says “Wristband”, and a search in your own words can return plausible results that miss it. discover_vocabulary maps your words to the repository’s names.

Terminal

rql vocabulary discover "end a user's sessions" \
  --question "What does this codebase call a user's signed-in session?" \
  --uri-glob "src/**" --token-budget 1000

Output

Names
- SignOut · 59.7% -> file:///src/auth/SignOut.cs
- Execute · 38.8% -> file:///src/auth/SignOut.cs#line=7,11&symbol=Demo.Auth.SignOut.Execute
- TokenStore · 45.3% -> file:///src/auth/TokenStore.cs
- TokenService · 44.8% -> file:///src/auth/TokenService.cs
- cli session · 32.5% -> file:///src/cli/CliSession.cs#line=6,22&symbol=Demo.Cli.CliSession
- RevokeCliTokens · 23.1% -> file:///src/auth/TokenService.cs#line=10,10&symbol=Demo.Auth.TokenService.RevokeCliTokens
…
Docs
- Wristband · 74.3% -> vocabulary:///Wristband.md
- SignOutRevokesCliTokens · 48% -> concept:///rule/auth/SignOutRevokesCliTokens.md
- RefreshBeforeExpiry · 38% -> concept:///rule/auth/RefreshBeforeExpiry.md
- RefreshReplacesTheToken · 25% -> concept:///knowledge/auth/RefreshReplacesTheToken.md#capsule-refreshreplacesthetoken
confidence: 55%+ strong · 30-55% lead · <30% noise

Output trimmed at …. Wristband is the strongest match: the team’s word for a session. SignOut, RevokeCliTokens and TokenStore are the names to search with next.

Find where the behaviour lives

Give explore the names you just learned as keywords, and your question. The question orders the results by how well they answer it.

Terminal

rql explore "SignOut Wristband revoke CLI tokens" \
  --question "What happens to a user's CLI tokens when they sign out?" \
  --uri-glob "src/**" --token-budget 600

Output

file:///src/auth/
100% /SignOut.cs
  SignOut | Execute | 13 ln, ~0.1k tok
  addresses: #symbol=<name>
  Demo.Auth
    // Ends a user's sessions when they sign out.
    +class SignOut
      // Signs the user out: ends every Wristband and revokes their CLI tokens.
      +Execute(string userId)
      +SignOut(WristbandStore wristbands, TokenStore tokens)    #symbol=SignOut.SignOut

 49% /TokenStore.cs
  TokenStore | Add, RevokeCliTokens, RemoveAll, Replace | 37 ln, ~0.4k tok

 47% /TokenService.cs
  TokenService | Issue, RevokeCliTokens, Refresh | 15 ln, ~0.1k tok

Relevant concepts:
concept:///rule/auth/SignOutRevokesCliTokens.md  file:///src/auth/**
  Signing a user out also revokes their CLI tokens.
…

Output trimmed at …. SignOut.Execute is where sign-out happens. Two files declare RevokeCliTokens. The constructor settles which one matters: the tokens that SignOut holds is a TokenStore. Below the matches, explore lists the concepts that cover these files.

Read the exact code

A score is a lead, not proof. Read the declarations themselves with read. Separate addresses with ; to get several in one call.

Terminal

rql read "src/auth/SignOut.cs#symbol=SignOut.Execute;src/auth/TokenStore.cs#symbol=TokenStore.RevokeCliTokens" \
  --token-budget 600

Output

base: file:///src/auth/
addresses: #symbol=<name>

--- SignOut.cs#line=7,11&symbol=Demo.Auth.SignOut.Execute ---
    public void Execute(string userId)
    {
        wristbands.EndAll(userId);
        tokens.RevokeCliTokens(userId);
    }

--- TokenStore.cs#line=18,18&symbol=Demo.Auth.TokenStore.RevokeCliTokens ---
    public void RevokeCliTokens(string userId) => RemoveAll(userId);

Sign-out ends the user’s Wristbands, then calls RevokeCliTokens, which removes all of the user’s tokens. You joined those two lines by reading the constructor. Now check the join.

Check the answer

Ask the index where Execute’s calls go. Then read the concepts that cover the file: the team’s recorded rules for this code.

Terminal

rql read "src/auth/SignOut.cs#symbol=SignOut.Execute => references"

Output

Resolved references
file:///src/auth/SignOut.cs#line=7 → file:///src/auth/TokenStore.cs#line=18,18&symbol=Demo.Auth.TokenStore.RevokeCliTokens

Name-level references (unresolved)
file:///src/auth/SignOut.cs#line=7 → EndAll

[1 resolved · 0 external · 1 name-level · 0 unresolved not evaluated]

The token call resolves to TokenStore.RevokeCliTokens, the method you read. EndAll does not resolve, because WristbandStore is not declared in this repository. An unresolved reference is a gap in the evidence, not proof the call is wrong. It does not affect this question. The source line shown is where Execute starts, not the line of the call.

Terminal

rql read "src/auth/SignOut.cs => concepts: sign out" --token-budget 250

Output

concept:///rule/auth/SignOutRevokesCliTokens.md (3 files) Signing a user out also revokes their CLI tokens.
…
**Invariant**
Signing a user out also revokes their CLI tokens.

**Why**
Sign-out ended the user's Wristbands, but the CLI signs in with its own token, so a signed-out user's CLI kept working.
…

Output trimmed at …: the concept’s header fields and two further concepts. The rule records the intent and the reason for it. A concept is a claim, not proof. Here the code you read and the resolved reference both agree with it.

Ask for an explanation, then check it

explain reads the scope and returns a cited answer. It is useful for covering ground you have not read. Treat each claim as something to check.

Terminal

rql explain "What happens to a user's CLI tokens when they sign out?" \
  --keywords "SignOut RevokeCliTokens Wristband TokenStore CliSession" \
  --uri-glob "src/**" --token-budget 800

Output

## What happens to a user's CLI tokens when they sign out?

<Answer>
When a user signs out, all of their CLI tokens are revoked — removed from the token store entirely, so the CLI stops working until they sign in again.
…
</Answer>
<Evidence>
- `file:///src/auth/SignOut.cs#symbol=SignOut.Execute` (lines 7–11): `Execute` calls `wristbands.EndAll(userId)` then `tokens.RevokeCliTokens(userId)`.
- `file:///src/auth/TokenStore.cs#symbol=TokenStore.RevokeCliTokens` (line 18): `public void RevokeCliTokens(string userId) => RemoveAll(userId);`
- `file:///src/auth/TokenStore.cs#symbol=TokenStore.RemoveAll` (lines 21–25): loops over `_tokens` entries matching the userId and removes each token.
</Evidence>
…

Output trimmed at …. The cited lines match what you read in step 3. One claim has no citation: “the CLI stops working until they sign in again”. The CLI keeps itself signed in through TokenService.Refresh, which calls TokenStore.Replace. Read that:

Terminal

rql read "src/auth/TokenStore.cs#symbol=TokenStore.Replace"

Output

    public string Replace(string token)
    {
        if (!_tokens.TryGetValue(token, out var entry) || entry.ExpiresAt <= clock.GetUtcNow())
            throw new UnauthorizedAccessException("Token is unknown or expired; sign in again.");

        _tokens.Remove(token);
        return Add(entry.UserId);
    }

A removed token is unknown, so its next refresh is refused with “sign in again”. That confirms the uncited claim for refresh. Report it with its limit: you have seen the refresh path refuse a revoked token, not every place the CLI uses one.

When it goes wrong

Symptom	Likely cause	What to do
`discover_vocabulary` lists names but no addresses	The budget fits only the names-only view.	Raise `--token-budget`.
A call appears under Name-level references (unresolved)	The index could not match it to a declaration. The type may live outside the repository, or may not declare that method.	Read the receiver’s type with `=> structure` before you rely on the call.
A second `explore` shows fewer or no Relevant concepts	Each concept is shown once per session.	Read them directly with `=> concepts`.
An `explain` answer states something its evidence does not cite	It summarises beyond what it read.	Read the code behind that claim before you repeat it.

What you’ve done

You translated your words into the repository’s names, and searched with them. You read the exact declarations rather than trusting a score. You checked the join against the index and the team’s concepts, then checked an explanation claim by claim. Your answer now cites the code behind each part.

Further reference

In the installed manual: help:///tools/discover-vocabulary.md, help:///tools/explore.md, help:///tools/read.md and help:///commands/explain.md.