grace-fix
Scannednpx machina-cli add skill osovv/grace-marketplace/grace-fix --openclawDebug an issue using GRACE semantic navigation.
Process
Step 1: Locate via Knowledge Graph
From the error/description, identify which module is likely involved:
- Read
docs/knowledge-graph.xmlfor module overview - Follow CrossLinks to find the relevant module(s)
- Read the MODULE_CONTRACT of the target module
Step 2: Navigate to Block
If the error contains a log reference like [Module][function][BLOCK_NAME]:
- Search for
START_BLOCK_BLOCK_NAMEin the codebase — this is the exact location - Read the containing function's CONTRACT for context
If no log reference:
- Use MODULE_MAP to find the relevant function
- Read its CONTRACT
- Identify the likely BLOCK by purpose
Step 3: Analyze
Read the identified block and its CONTRACT. Determine:
- What the block is supposed to do (from CONTRACT)
- What it actually does (from code)
- Where the mismatch is
Step 4: Fix
Apply the fix WITHIN the semantic block boundaries. Do NOT restructure blocks unless the fix requires it.
Step 5: Update Metadata
After fixing:
- Add a CHANGE_SUMMARY entry with what was fixed and why
- If the fix changed the function's behavior — update its CONTRACT
- If the fix changed module dependencies — update knowledge-graph.xml CrossLinks
- Run type checking or linting to verify
Important
- Never fix code without first reading its CONTRACT
- Never change a CONTRACT without user approval
- If the bug is in the architecture (wrong CONTRACT) — escalate to user, don't silently change it
Source
git clone https://github.com/osovv/grace-marketplace/blob/main/codex-skills/grace-fix/SKILL.mdView on GitHub Overview
GRACE-fix helps you debug issues by navigating the knowledge graph to identify the implicated module and the exact semantic block. It compares the CONTRACT with the implementation, pinpoints mismatches, and applies targeted fixes within the block boundaries, preserving architecture and contracts.
How This Skill Works
It starts by locating the likely module from the error using the knowledge graph and MODULE_CONTRACT. If logs reference a specific block, it jumps to START_BLOCK_BLOCK_NAME; otherwise it uses MODULE_MAP to map to the right function and its CONTRACT. It then analyzes the block to find the mismatch and applies the fix strictly within the semantic block, followed by metadata updates and a lint/type check pass.
When to Use It
- When you encounter bugs, errors, or unexpected behavior and need to locate the responsible module via the knowledge graph.
- When error logs reference [Module][function][BLOCK_NAME] and you need to navigate to the exact START_BLOCK_BLOCK_NAME.
- When no log reference exists but you can map to a function via MODULE_MAP and read its CONTRACT.
- When there is a mismatch between what the contract specifies and what the code implements.
- When you need to fix within semantic block boundaries and then update CHANGE_SUMMARY and possibly CONTRACT.
Quick Start
- Step 1: Locate the involved module from the error using knowledge-graph.xml and MODULE_CONTRACT.
- Step 2: Navigate to the correct block using START_BLOCK_BLOCK_NAME (or MODULE_MAP to find the function) and read its CONTRACT.
- Step 3: Analyze the mismatch, apply the fix within the semantic block, then update CHANGE_SUMMARY and run type checks.
Best Practices
- Always read the CONTRACT before touching code.
- Use docs/knowledge-graph.xml and CrossLinks to locate the correct module.
- If a log references a BLOCK_NAME, locate START_BLOCK_BLOCK_NAME precisely.
- Fix only within the identified semantic block unless a broader change is required.
- After fixing, update CHANGE_SUMMARY and re-run type checking or linting.
Example Use Cases
- Auth module: CONTRACT requires token validation; fix implemented inside START_BLOCK_TOKEN_VALIDATION to ensure expiry checks align with contract.
- Checkout price calc: CONTRACT specifies 2-decimal pricing; corrected within BLOCK_PRICE_CALC to enforce exact decimal handling.
- Data fetch: CONTRACT requires caching; added minimal cache within BLOCK_FETCH to meet performance expectations.
- Notification formatting: log shows [Module][sendNotif][BLOCK_FORMAT]; corrected message formatting inside BLOCK_FORMAT without altering other blocks.
- Contract update: new validation step added to CONTRACT; updated implementation and refreshed knowledge-graph CrossLinks accordingly.
