osovv/grace-fix

Debug an issue using GRACE semantic navigation.

Process

Step 1: Locate via Knowledge Graph

From the error/description, identify which module is likely involved:

1. Read docs/knowledge-graph.xml for module overview
2. Read docs/verification-plan.xml for relevant scenarios, test files, or log markers if available
3. Read docs/operational-packets.xml for the canonical FailurePacket shape if available
4. Follow CrossLinks to find the relevant module(s)
5. Read the MODULE_CONTRACT of the target module

If the optional grace CLI is available, you may use:

• grace module find <query> --path <project-root> to resolve likely module IDs from stack traces, paths, verification refs, or dependency names
• grace module show M-XXX --path <project-root> --with verification to pull the shared/public module and verification snapshot
• grace file show <path> --path <project-root> --contracts --blocks when you already know the governed file and need its local/private navigation surface

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 the failure came from a named verification scenario or test:

• read the matching V-M-xxx entry in docs/verification-plan.xml
• open the mapped test file and expected evidence for that scenario

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, its CONTRACT, and relevant verification entry. Determine:

• What the block is supposed to do (from CONTRACT)
• What evidence should prove that behavior (from tests, traces, or log markers)
• 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:

1. Add a CHANGE_SUMMARY entry with what was fixed and why
2. If the fix changed the function's behavior — update its CONTRACT
3. If the fix changed module dependencies — update knowledge-graph.xml CrossLinks
4. If the fix changed tests, commands, or required markers — update docs/verification-plan.xml
5. Run the relevant module-local verification commands
6. 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