Tool

discover_vocabulary

Learn what a repository calls the thing you’re looking for. Describe it in your own words, and discover_vocabulary returns the repository’s names for it, each with a confidence and an address.

Describe it your way

Keywords are the rough words you already have. Several related terms are fine, such as throttle, debounce, rate limit. You don’t need to guess the right name; that is what the tool is for.

A question says what you want to know about those words: “What does this codebase call a user’s signed-in session?” It sharpens the ranking.

Reach for it before explore when the names are unfamiliar. Reach for it again when explore comes back weak. On a fully indexed repository, weak matches usually mean you are searching with your words, not the repository’s.

Read the confidence

Each term carries a percentage. 55% or more is a strong hit. 30% to 55% is a lead worth checking. Under 30% is noise. The legend is printed under every result, so you don’t need to remember it.

Terms are grouped by where they came from: Names from declarations, Config & paths from settings and file paths, Tests from test code, and Docs from documents, concepts and vocabulary. Within a group, terms are in the tool’s rank order. That order doesn’t always match the percentages, so read the percentage.

When your own words name something real and relevant, they open the result under Confirmed, with the address that proves it. A word of yours that isn’t confirmed names nothing strong in this repository. Confirmation needs reranking, which runs in the cloud.

Your team’s words count

The search includes your team’s concepts and vocabulary, not only code. In this example, the code says “Wristband” for a session. The word appears in SignOut.cs only inside a parameter type and in comments, so before the vocabulary entry was added, this search didn’t return it. After one rql vocabulary add, it is the strongest result.

Terminal

rql vocabulary add Wristband "A user's signed-in session." \
  --aliases "session;login session" --uri-glob "file:///src/auth/**"

Output

Captured term: vocabulary:///Wristband.md
- session — already present in corpus
- login session — absent from corpus

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 600

Output

Names
- SignOut · 59.7% -> file:///src/auth/SignOut.cs
- Execute · 36.5% -> file:///src/auth/SignOut.cs#line=7,11&symbol=Demo.Auth.SignOut.Execute
- TokenService · 44.8% -> file:///src/auth/TokenService.cs
- RevokeCliTokens · 24.4% -> file:///src/auth/TokenService.cs#line=10,10&symbol=Demo.Auth.TokenService.RevokeCliTokens
- Invoice · 17% -> file:///src/billing/Invoice.cs
- Total · 15.9% -> file:///src/billing/Invoice.cs#line=4,4&symbol=Demo.Billing.Invoice.Total
- Issue · 20.7% -> file:///src/auth/TokenService.cs#line=7,7&symbol=Demo.Auth.TokenService.Issue
- Refresh · 20.5% -> file:///src/auth/TokenService.cs#line=13,13&symbol=Demo.Auth.TokenService.Refresh
- Id · 15.7% -> file:///src/billing/Invoice.cs#line=4,4&symbol=Demo.Billing.Invoice.Id
Docs
- Wristband · 74.3% -> vocabulary:///Wristband.md
- SignOutRevokesCliTokens · 52.3% -> concept:///rule/auth/SignOutRevokesCliTokens.md
confidence: 55%+ strong · 30-55% lead · <30% noise

• The adding command reports each alias. “Already present in corpus” means the word already appears in your repository, so that alias adds less than one that doesn’t.
• The team’s word wins. Wristband comes first at 74.3%, from the vocabulary entry. SignOut is the strongest code name.
• Addresses point at each name, so you can pass them to read or use the names as explore keywords.
• Noise is labelled. The billing names score under 30%. They are there because the scope includes src/billing.

Use the names as search terms, not answers. A strong name tells you what to search for. It doesn’t prove what the code does. Read the code before you rely on it.

Budget and scope

The token budget chooses how much each term shows. In the example, a budget of 150 returns names and percentages only. 600 adds addresses, as shown. 2,000 adds a one-line summary for each term. At most 20 terms are shown at any budget.

The scope is an address that limits where to look. By default it covers the repositories you work in, plus their concepts and vocabulary. Imported repositories are left out until you name one, such as github://acme/platform/**. If tests are in scope, test names can crowd out the ones you want.

What it can’t see

Candidate names come from naming surfaces: declarations, headings, settings keys and filenames. A word that lives only in comments or prose won’t come back, as Wristband showed before it was recorded.

Behaviour connected through dependency injection, attributes or event registration is hard to find by name. For those, search with explore using the best names you found, or use query to list the types that implement an interface.

Parameters

Further reference

In the installed manual: help:///tools/discover-vocabulary.md and help:///commands/vocabulary.md.