grace-refresh
npx machina-cli add skill osovv/grace-marketplace/grace-refresh --openclawSynchronize the knowledge graph with the actual codebase.
Process
Step 1: Scan Codebase
Find all source files in the project. For each file, extract:
- MODULE_CONTRACT (if present)
- MODULE_MAP (if present)
- All imports (to determine dependencies)
- CHANGE_SUMMARY (if present)
Step 2: Compare with Knowledge Graph
Read docs/knowledge-graph.xml. Identify:
- Missing modules: files with MODULE_CONTRACT that are not in the graph
- Orphaned modules: graph entries whose files no longer exist
- Stale CrossLinks: dependencies in the graph that don't match actual imports
- Missing contracts: files that have no MODULE_CONTRACT at all
Step 3: Report Drift
Present a structured report:
GRACE Integrity Report
=======================
Synced modules: N
Missing from graph: [list files]
Orphaned in graph: [list entries]
Stale CrossLinks: [list]
Files without contracts: [list files]
Step 4: Fix (with user approval)
For each issue, propose a fix:
- Missing from graph — add entry using unique ID-based tag (M-xxx NAME="..." TYPE="...") with fn-name, type-Name annotation tags. See AGENTS.md "Documentation Artifacts" for full convention.
- Orphaned — remove from graph
- Stale links — update CrossLinks from actual imports
- No contracts — generate MODULE_CONTRACT from code analysis
Ask user for confirmation before applying fixes.
Step 5: Update Graph
Apply approved fixes to docs/knowledge-graph.xml. Update version.
Source
git clone https://github.com/osovv/grace-marketplace/blob/main/codex-skills/grace-refresh/SKILL.mdView on GitHub Overview
Grace-refresh synchronizes the GRACE knowledge graph with the live codebase to prevent drift after edits or refactoring. It scans all source files for MODULE_CONTRACT, MODULE_MAP, imports, and CHANGE_SUMMARY, then compares them with the graph to surface missing modules, orphans, and stale CrossLinks. With user approval, fixes are proposed and applied to update docs/knowledge-graph.xml and versioning.
How This Skill Works
Its workflow is five steps: scan codebase for MODULE_CONTRACT MODULE_MAP imports and CHANGE_SUMMARY; compare against docs/knowledge-graph.xml to spot drift; present a structured drift report; propose fixes with a unique ID based tagging and require confirmation; update the graph after approval and bump the version.
When to Use It
- After manual code changes or refactoring
- When you suspect drift between the knowledge graph and the code
- When auditing for missing or orphaned modules
- When dependencies or CrossLinks have changed
- When validating and syncing legacy or new files without contracts
Quick Start
- Step 1: Run a scan of the codebase to collect MODULE_CONTRACT MODULE_MAP all imports and CHANGE_SUMMARY
- Step 2: Compare with docs knowledge-graph.xml to identify Missing from graph Orphaned in graph Stale CrossLinks and Files without contracts
- Step 3: Review the GRACE Integrity Report and apply approved fixes to docs/knowledge-graph.xml, then update the version
Best Practices
- Run Grace-refresh after code changes or refactors
- Ensure every file with code has a MODULE_CONTRACT or address missing contracts
- Review the drift report carefully before applying fixes
- Follow the AGENTS.md Documentation Artifacts conventions for fixes
- Update docs/knowledge-graph.xml with approved changes and version it
Example Use Cases
- Feature addition changes module layout and drift is detected between graph and code
- Orphaned graph entries removed after code deletion
- Stale CrossLinks corrected to reflect actual imports
- Legacy files lacking MODULE_CONTRACTs are analyzed and contracts generated
- Codebase modernization where imports are reorganized and graph updated
