Debug 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.xml for 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_NAME in 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

• If the failure revealed weak tests, weak logs, or poor execution-trace visibility — use $grace-verification to strengthen automated checks before considering the issue fully closed

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