Guide

Keep what you learn

Turn one real discovery into a concept the next session can act on. You’ll finish with a fact-checked concept file, committed next to the code it describes.

The route

Choose a lesson worth keeping. Pick something that will change future work, and check it isn’t already written down.
Write the rule and its reason. One sentence someone can act on, then the mechanism behind it.
Point it at code. Relevance says where it applies. Verification names the exact evidence.
Capture it and read the verdict. The checker reads your evidence and tells you what it could not confirm.
Review and commit the file. The concept is a file, so it ships like code.

The example is a small auth service. While debugging, you found that a CLI which misses its refresh window cannot refresh at all: TokenStore.Replace refuses an expired token, so the user has to sign in again.

Choose a lesson worth keeping

Keep a lesson when someone will face the same decision again: a platform constraint, a boundary between components, a check that catches a misleading result. Task status and personal preferences don’t belong here. Neither does a bug you can simply fix: fix it instead.

Before writing anything, see what already applies to the files involved.

Terminal

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

Output

No concepts are relevant to file:///src/cli/**. Browse all: read("concept:///**").

Terminal

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

Output

concept:///knowledge/auth/RefreshReplacesTheToken.md (3 files) Refreshing a CLI token issues a new token in place of the old one.
…
concept:///rule/auth/SignOutRevokesCliTokens.md (3 files) Signing a user out also revokes their CLI tokens.
…

RefreshReplacesTheToken is close, but it describes what a refresh does, not when it stops working. So this is a new concept. If an existing concept already said the same thing, you would capture again under its name. That replaces it, rather than leaving two competing versions.

Write the rule and its reason

The invariant is one idea in one sentence: The CLI must refresh its token before the token expires. If you want to write “and”, you probably have two concepts.

The why is for a reader who wasn’t there. Name the mechanism and the consequence: TokenStore.Replace refuses an expired token, so the user has to sign in again. An example makes it concrete: a laptop that sleeps through the refresh window wakes up signed out.

Point it at code

Relevance is where the rule applies, which is not always where you learned it. The mistake would be made in the CLI, and the cause is in auth, so name both. Relevance must match files that exist.

Terminal

rql concept add RefreshBeforeExpiry rule \
  "The CLI must refresh its token before the token expires." \
  --tags "refresh,cli tokens,expiry,RefreshReplacesTheToken" \
  --relevance "file:///src/client/**" --contextual

Output

Concept validation failed.
- relevance: Relevance 'file:///src/client/**' matched no indexed files under file://. Check the path or use a schemeless glob such as **/Name.cs for mount-agnostic matching.
Help: rql read "help:///tools/capture-concept.md" — Capture concept help

Nothing was written. The CLI code lives in src/cli/, not src/client/.

Verification names the evidence. Anchor it to a symbol, such as TokenStore.cs#symbol=TokenStore.Replace, not a folder. The checker then reads that declaration’s code, and the address follows it when lines move.

Pass --contextual when the rule can only be broken while working in the files it names. Without it, the CLI records the concept as universal, loaded into every session.

Capture it and read the verdict

A first draft often states what you assumed rather than what you proved. Here the draft says the CLI recovers on its own.

Terminal

rql concept add RefreshBeforeExpiry rule \
  "The CLI signs the user in again when its token has expired." \
  --tags "refresh,cli tokens,expiry,RefreshReplacesTheToken" \
  --relevance "file:///src/cli/**;file:///src/auth/**" \
  --verification "file:///src/auth/TokenStore.cs#symbol=TokenStore.Replace;file:///src/cli/CliSession.cs#symbol=CliSession.KeepAlive" \
  --ttl-days 180 --subcategory auth --contextual

Output

Captured concept: concept:///rule/auth/RefreshBeforeExpiry.md
Path: .repoql/concepts/rule/auth/RefreshBeforeExpiry.md
Verification: passed - WARN - The evidence shows the CLI refreshes its token *before* expiry (KeepAlive's RefreshWindow check) and that expired tokens are refused with a "sign in again" error (TokenStore.Replace), but nothing establishes that the CLI actually signs the user in again after expiry — the invariant's timing (after expiry) is contradicted by the refresh-before-expiry mechanism.  Craft: The invariant describes a behavior the code doesn't implement (re-auth after expiry); rewording it to "the CLI refreshes its token before it expires" would match the evidence and be verifiable.

When the checker judges a claim false, it refuses and nothing is written. A WARN, as here, still writes the file. Don’t stop there. A warning that says your claim isn’t established means the claim is wrong or the evidence is missing. Rewrite the claim, or add the evidence, and capture again under the same name.

Terminal

rql concept add RefreshBeforeExpiry rule \
  "The CLI must refresh its token before the token expires." \
  --why "TokenStore.Replace refuses an expired token, so a CLI that misses the refresh window cannot recover by refreshing. The user has to sign in again." \
  --example "A laptop that sleeps through the last five minutes of a token's life wakes to a CLI that is signed out." \
  --tags "refresh,cli tokens,expiry,RefreshReplacesTheToken" \
  --relevance "file:///src/cli/**;file:///src/auth/**" \
  --verification "file:///src/auth/TokenStore.cs#symbol=TokenStore.Replace;file:///src/cli/CliSession.cs#symbol=CliSession.KeepAlive" \
  --ttl-days 180 --subcategory auth --contextual

Output

Captured concept: concept:///rule/auth/RefreshBeforeExpiry.md
Path: .repoql/concepts/rule/auth/RefreshBeforeExpiry.md
Verification: passed - PASS - — TokenStore.Replace throws UnauthorizedAccessException for expired tokens, and CliSession.KeepAlive refreshes whenever the token is within RefreshWindow of expiry, establishing the refresh-before-expiry invariant.  Craft: The Example's "sleeps through the last five minutes" scenario depends on RefreshWindow's actual value; consider citing the RefreshWindow constant so the example stays verifiable as code drifts.

PASS means the evidence supports the rule. The craft note is advice and doesn’t change the verdict. Act on it if it would help the next reader.

Review and commit the file

Read the file as someone who wasn’t in the session. Could they apply it correctly from this alone?

Terminal

cat .repoql/concepts/rule/auth/RefreshBeforeExpiry.md

Output

---
description: "The CLI must refresh its token before the token expires."
…
category: rule
subcategory: auth
universal: false
relevance: "file:///src/cli/**;file:///src/auth/**"
verification: "file:///src/auth/TokenStore.cs#symbol=TokenStore.Replace;file:///src/cli/CliSession.cs#symbol=CliSession.KeepAlive"
ttl: 180
verified:
  date: "2026-09-29"
  commit: "182a5aaa9e85"
---

## Capsule: RefreshBeforeExpiry

**Invariant**
The CLI must refresh its token before the token expires.

**Why**
TokenStore.Replace refuses an expired token, so a CLI that misses the refresh window cannot recover by refreshing. The user has to sign in again.

**Example**
A laptop that sleeps through the last five minutes of a token's life wakes to a CLI that is signed out.

The verified stamp records the date and the commit the checker judged against. RepoQL checks the evidence again after ttl days. The file is written, not committed, so commit it with the work it describes.

Terminal

git add .repoql/concepts/rule/auth/RefreshBeforeExpiry.md && git commit -m "concept: RefreshBeforeExpiry" -- .repoql/concepts/rule/auth/RefreshBeforeExpiry.md

Output

[main b4e3c6d] concept: RefreshBeforeExpiry
 1 file changed, 28 insertions(+)
 create mode 100644 .repoql/concepts/rule/auth/RefreshBeforeExpiry.md

Run the first command again. src/cli/** now returns concept:///rule/auth/RefreshBeforeExpiry.md, so an agent working on the CLI will see it. When the constraint changes, update the concept or delete the file.

When it goes wrong

Symptom	Likely cause	What to do
`Concept validation failed.` with a `relevance` line	The relevance matches no indexed files	Fix the path so it names folders that hold indexed files
`Concept validation failed.` with a `verification` line	A knowledge concept has no verification	Add evidence and `--ttl-days`, or use `rule` if nothing can check it
`passed - WARN` and the summary says the claim isn’t established	The claim goes beyond the evidence	Narrow the claim or cite the code that proves it, then capture again under the same name
`Concept fact-check failed; nothing was written.`	The evidence contradicts the claim, or the check couldn’t finish	Read the summary. Correct the claim, or retry if the check errored
`Verification skipped because inference is unavailable.`	You aren’t signed in to cloud inference	The file is written unchecked. Sign in with `rql account login` and capture again

What you’ve done

You checked what the repository already knew, then wrote one rule with its reason. You pointed it at the files where it applies and the code that proves it. You read the checker’s warning, corrected the claim and committed the verified file.

Further reference

The capture_concept tool page and Concepts. In the installed manual: help:///tools/capture-concept.md, help:///commands/concept.md.