Guide

Keep what you learn

Record the reason behind a repository rule while you still have the evidence. Future sessions can then use that understanding without repeating the investigation.

A useful concept explains a decision someone will face again: what must remain true, why it matters, and where it applies. RepoQL stores these concepts as ordinary Markdown under .repoql/concepts/, so they can be reviewed and versioned with the code.

Choose a lesson that will affect future work

Good candidates include a platform constraint, an architectural boundary, or a verification step that catches a misleading result. Temporary task status and personal working preferences usually belong in session notes.

Prefer a statement a future reader can act on. “We had a difficult deployment” records an experience. A rule naming the condition that made the deployment fail helps someone avoid repeating it.

Separate the rule from its explanation

Write the central statement in one short sentence. Put the mechanism and consequences in why, and use an example to show how the rule applies. Split the concept when it contains independent decisions that belong in different places.

For example, this repository’s website rule requires published commands to have been run against the binary. Its explanation is that command syntax can drift even when the prose looks correct. Its relevance is the website source, where someone can act on the rule.

Make it appear in the right context

Set relevance to the files where the idea applies. Contextual concepts can be surfaced during RepoQL-assisted work in that area. Universal concepts belong in the general index an agent receives; reserve that placement for guidance needed before it chooses a file.

Check the existing concepts first. Updating a rule with better evidence is usually more useful than adding a competing version with a slightly different name.

Anchor factual claims to evidence

Use verification sources that directly support the claim. A symbol address can track a declaration as its line numbers change, though a rename or move can still require an updated address. External constraints can cite the provider’s documentation.

For verifiable categories, supply a positive ttlDays interval with the evidence. Read the checker’s result: a saved file can have skipped or inconclusive verification. Model-based checking helps review a claim, but does not guarantee it remains true after later changes.

Review the saved file with the code

Use capture_concept to write the concept, then read the result. Check whether a person unfamiliar with the original task could apply it correctly. Commit it with the relevant work so the rule and its evidence can be reviewed together.

When the constraint changes, update or remove the concept. The value is the explanation it gives the next reader, not the amount of history the collection accumulates.

Read the existing collection

Terminal

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

Terminal

rql read "concept:///** => structure" --token-budget 2000

The first command selects concepts relevant to cloud source in RepoQL.Core. The second surveys the stored concepts. Use your repository’s scope when looking for guidance about a particular subsystem.

Further reference

In the installed manual: help:///tools/capture-concept.md, help:///commands/concept.md.