Debugging with Context Engine

When to Use

• "Why is this function failing?"
• "Trace where this error / log message comes from"
• "Who calls this method?"
• "This endpoint returns 500 / a wrong value"
• Investigating bugs, errors, or unexpected behavior

Workflow

1. list-repos                                              → repoId + freshness check
2. codebase-retrieval({repoId, information_request: "<error text or symptom>"})
                                                           → locate suspect symbols + their snippets
3. Follow [callers:…] / [calls:…] to trace inward/outward from the suspect
4. file-retrieval({repoId, file_path, information_request}) → pinpoint the failing branch
5. Read <file>:<lines>                                     → confirm root cause

If the index is stale (lastCommitSha ≠ local HEAD), recent changes won't be searchable → push first (context-engine-sync).

Checklist

- [ ] Capture the exact symptom (error message, status code, unexpected value)
- [ ] codebase-retrieval for the error TEXT or the behavior in natural language
- [ ] Identify the suspect symbol from the ranked snippets
- [ ] Use [callers:…] to see who reaches it, [calls:…] for downstream/external deps
- [ ] file-retrieval to zoom into the failing function
- [ ] Read source at the returned lines to confirm before fixing

Debugging Patterns

Tools

codebase-retrieval — find code related to the error:

codebase-retrieval({repoId, information_request: "SSE streaming response re-stream ZlibError accept-encoding"})
→ core/apps/registry/src/api/bff-data.routes.ts#L290-362  (accept-encoding: identity to avoid Bun ZlibError)

file-retrieval — narrow to the failing branch in a known file:

file-retrieval({repoId, file_path: "apps/models-router/apps/api/src/api/public.routes.ts",
                 information_request: "where usage buckets are aggregated by model"})

Note: codebase-retrieval has NO git-history awareness — it reflects only the last indexed snapshot. For "what changed recently" use git log/git diff; for "what does my current diff affect" read the changed files directly.

Example: "Models-router /public usage endpoint returns wrong totals"

1. list-repos → repoId, status=indexed
2. codebase-retrieval({repoId, information_request: "public usage stats aggregation by request_model and bucket"})
   → apps/models-router/apps/api/src/api/public.routes.ts (modelBucketMap aggregation)
3. file-retrieval on public.routes.ts: "how the bucket key is built"
   → key uses `${request_model}\0${bucket}` (NUL separator)
4. Read the aggregation block → confirm the bucketing logic / off-by-one