codehub-debugging

Debugging with OpenCodeHub

When to Use

• "Why is this function failing?"
• "Trace where this error comes from."
• "Who calls this method?"
• "This endpoint returns 500 intermittently."
• Investigating bugs, errors, test failures, or unexpected behaviour.

Workflow

1. mcp__codehub__detect_changes                              → Is this a recent regression?
2. mcp__codehub__query({ query: "<error or symptom>" })      → Find code related to the symptom
3. mcp__codehub__context({ name: "<suspect>" })              → Callers, callees, processes, cochanges
4. mcp__codehub__sql for a process trace                     → Ordered PROCESS_STEP chain
5. mcp__codehub__list_findings                               → SARIF findings that already flagged the area
6. Read source files only after the graph has narrowed the suspect set

If the context envelope warns the index is stale, run codehub analyze first — stale graphs point at the wrong suspect.

Checklist

- [ ] Capture the symptom (error text, stack frame, failing assertion, wrong output)
- [ ] mcp__codehub__detect_changes({ scope: "unstaged" | "staged" })
      — if non-empty, recent edits are the primary suspect
- [ ] mcp__codehub__query for the error text or related concept
- [ ] mcp__codehub__context on the suspect symbol
- [ ] Read confidenceBreakdown — if unknown > 0, an LSP contradicted a heuristic edge;
      the suspect may be a stale or dead reference
- [ ] Review cochanges (git-history signal, NOT call deps) — files historically edited
      together often point at the hidden collaborator
- [ ] Trace the execution via mcp__codehub__sql on PROCESS_STEP edges
- [ ] mcp__codehub__list_findings to see if a scanner already flagged the area
- [ ] Read source to confirm root cause

Debugging Patterns

Symptom	OpenCodeHub path
Error message	query for the error text → context on every throw site it returned
Wrong return value	context on the function → trace outgoing CALLS for the data flow
Intermittent failure	context → look for outgoing FETCHES (external I/O) + cochanges
Performance issue	impact (downstream) → find symbols with many outbound CALLS (hot paths)
Recent regression	detect_changes → symbols touched in the working tree or staged diff
Failing scanner gate	list_findings({ severity: "error" }) → read the rule + the hit line