Skip to content

RAGRAF Core

The skill of working with the RAGRAF core: how to get a fact from the index, how to recognize a fact that must not be trusted, and what to do when the index is broken. Everything rests on the files of the <repository> project; wherever a file:line appears, it was verified by reading, not from memory.

The project rules live in AGENTS.md at the project root (read automatically; not shipped in the public repository), the deep passport is docs/AGENTS-context.md (not shipped), and the convention checker is tools/Invoke-ProjectDoctrine.ps1.

1. When this skill applies

  • An answer about the project's code is needed instead of reading files: where something is defined, who calls it, what will break, what is in a table, where a table is written, where a class is applied.
  • The index and the code diverged: a result looks stale, the revision is old, the guard reports a divergence.
  • The corpus does not answer: capability=degraded, an operation refuses, a slice is unavailable.
  • Exclusions, the language list or corpus settings are changing.
  • The development registry shows an empty revision or zeros against a live index.

2. The first step of any task — refresh the corpus

Facts come from the index, so a stale index is forbidden:

python tools/ragraf.py ensure <project directory>      # find, rebuild, create
python tools/ragraf.py -p config/ragraf.yaml check     # checksum comparison only

ensure answers with a status field: actual — the index is current, reindexed — just rebuilt, created — there was no corpus and one was created, not_a_project — the directory does not look like a project, error — the reason is in the reason field.

A stale marker in any operation's answer means the code has moved ahead and the index's facts are wrong. They must not be worked from.

3. Choosing an operation instead of reading files

Question Operation
«Where is the function or class defined» symbol
«Where is it described how something works» search
«Who calls it» / «what does it call» callers / callees
«What will an edit affect» impact
«The function body» (only when the text is needed) code
«What is in the table» / «who reads and writes it» schema / table_usage
«Is this write valid» — before writing SQL write_check
«Who gets a permission and under which condition» policy_trace
«Is there a rule in the styles, and where is the class applied» class_usage
«Is the index current» freshness, index_status
«Overall structure» repo_map
«What is registered in the registry» catalog
«The file's current content with difference marks» live_read

Through the shell this is python tools/ragraf.py -p <config> query <operation> …, through the agent's tools — ragraf_<operation>. The detailed choice breakdown is in reference/operations.md.

What an operation does not replace: full-text reading where details matter. symbol and code return a line range, not the whole file.

4. Hard rules

  1. A fact without a file:line reference is a guess. Back every meaningful conclusion with a code reference.
  2. Verify a number from a document against the code. The project has already diverged from its own documentation: the code declares 40 tools and 38 facade operations, while documents name 18, 16 and 21.
  3. Do not read secret-bearing files (the list is in AGENTS.md §6, not shipped): only the name, the size and the rule. There is no git history in the project — the only protection is not opening them.
  4. Do not run foreign code during reconnaissance. The project is executed only when the task is exactly about that.
  5. Do not treat selftest as a gate: it always returns exit code 0 (src/ragraf/cli.py:906).
  6. empty result is exit code 0 with found=false, not an error; exit code 3 means «the operation cannot run right now», e.g. a slice at capability != "full" (src/ragraf/cli.py:336-356).

5. What breaks most often

  1. The registry diverges from the index after ensure. src/ragraf/ensure.py:308-312 used to register the corpus before indexing without recording the run result. Measured: an entry with trigger register had empty rev_id/capability and node_count=0 while the index held 1855 nodes. (Fixed in the shipped code: ensure.py now calls record_index_run(..., trigger="ensure:index"); if you see zeros again — the recipe is in reference/repair.md.)
  2. An exclusion edit silently throws out working code. Matching is case-sensitive (src/ragraf/util.py:72-158); **/cache/** does not catch src/Cache/. Before extending the list — python tools/measure_safe_excludes.py (not shipped; see repair.md §4).
  3. Duplicate collapsing gets enabled without understanding the price. Enabling it changes the corpus checksum: the freshness guard reindexes the corpus once. The choice of the primary copy must be deterministic (src/ragraf/dedupe.py:165-223), otherwise reindexing never stops.
  4. capability=degraded gets mistaken for breakage. It is an honest mark: the CPG was not built, the slice is unavailable, everything else works. The reason is always written in index_status.
  5. The GPU is treated as a guarantee. The GPU compute path requires sentence-transformers and torch, which are not declared in the package description (src/ragraf/compute.py:141-146); the break-even threshold is 1800 texts for vectors and about 5000 vertices for the graph.

6. Order of work

  1. Refresh the corpus (ensure).
  2. Formulate the question in terms of an operation, not a file.
  3. Get facts with references and make sure the index is not marked stale.
  4. Read a whole file only where an operation does not answer the question.
  5. After editing the core:
python tools/ragraf.py -p config/ragraf.yaml reindex
python tools/ragraf.py -p config/ragraf.yaml check
pwsh -NoLogo -NoProfile -NonInteractive -File tools/Invoke-ProjectDoctrine.ps1
  1. The checker ships 14 checks. In the published tree 11 pass and 3 report files that are deliberately absent from the public subset (the corpus config, tests/test_dedupe.py, tests/test_text_from_index.py) — roadmap R-REL-1. The author's full tree records its own baseline in AGENTS.md §10 (not shipped). A new error or a new warning in the published tree is a finding either way.

7. Skill files

  • reference/operations.md — how to choose an operation and what it does not show.
  • reference/repair.md — recipes: stale index, empty registry, degraded, a looping guard, an exclusion mistake, falling back to the CPU computer.