/gaia-refresh-ground-truth
user-facingWhat it does
/gaia-refresh-ground-truth rescans the project filesystem and updates the ground-truth snapshot used by the validator. It discovers project structure, file inventory, and key metadata, compares against the previous snapshot, and writes a diff report of what changed. This keeps the validator's knowledge of your project current.
When to use it
- You notice validation findings about outdated file references and want to refresh the validator's knowledge.
- You added or reorganized files and want the validator to know about the changes before the next validation run.
- You want to refresh ground truth for a specific agent (validator, architect, PM, or scrum master).
Prerequisites
- No strict prerequisites. If the memory sidecar directory does not exist, it is created automatically.
How to invoke
/gaia-refresh-ground-truth
/gaia-refresh-ground-truth --agent all --incrementalWhat it does step by step
- Resolve agent target Determines which agent's ground truth to refresh (defaults to the validator). Supports val, theo, derek, nate, or all.
- Initialize sidecar directory Creates the memory sidecar directory and files if they do not exist.
- Parse previous state Reads the existing ground-truth file and extracts the last-refresh timestamp and all entries.
- Scan project Scans source files, config files, package manifests, planning artifacts, implementation artifacts, and test artifacts. Caps at 500 files per scan pattern.
- Compare and detect changes Classifies each entry as ADDED, UPDATED, or REMOVED compared to the previous state.
- Write ground truth Writes the updated ground-truth file with a new timestamp, mode, and entry count.
- Generate diff report Summarizes what changed: counts of added, removed, and updated entries.
- Budget check Checks the ground-truth file size against the configured token budget and surfaces archival guidance if usage exceeds the warning threshold.
Inputs
| Input | Source | Description |
|---|---|---|
--agent | Command argument (optional) | Which agent's ground truth to refresh. Default: val. |
--incremental | Command argument (optional) | Only scan files modified since the last refresh. |
Outputs
| Output | Location | Description |
|---|---|---|
| Updated ground truth | _memory/{agent}-sidecar/ground-truth.md | The refreshed ground-truth snapshot. |
| Diff report | Console output + decision log | Summary of additions, removals, and updates. |
Example session
> /gaia-refresh-ground-truth
Scanning project source files... found 156 files across 12 directories.
Scanning project config files... found 4 config files.
Scanning package manifests... found 1 manifest.
Scanning planning artifacts... found 6 artifacts.
Scanning implementation artifacts... found 23 artifacts.
Scanning test artifacts... found 4 artifacts.
Diff report:
Added: 8 new entries.
Removed: 2 entries.
Updated: 3 entries.
Total entries: 194.
val: 4,850/200,000 tokens (2%)
Ground truth refreshed.What to run next
/gaia-val-validate-- run a validation with the freshly updated ground truth./gaia-memory-hygiene-- if the budget check flagged high usage, review and archive stale entries.
Troubleshooting
No changes detected
The project has not changed since the last refresh. The timestamp is updated but content remains the same.
Scan truncated at 500 files
A glob pattern returned more than 500 results. The scan is capped to protect performance. Results may be incomplete for very large projects.