Debug Issue

Debug issue

Trace the call chain before hypothesizing. The failure this skill exists to prevent: proposing a fix before the call chain from symptom to entry point has actually been traced.

The workflow derives from the skill templates the code-review-graph project auto-installs (MIT, © 2026 Tirth Kanani), rewritten here to be tool-agnostic: every step carries a baseline that needs no graph server.

Steps

1. Locate the code from the symptom.

Accelerated: a code-graph semantic-search call (e.g. semantic_search_nodes-shaped; discover the real tool name from the server's own listing) finds relevant code by meaning, not string match. Baseline: grep for the error message, log line, or another distinctive identifier (field name, status code, exception type) across the source tree.

1. Trace callers and callees from that point — both directions, not just one.

Accelerated: a graph query for callers-of/callees-of the located symbol (e.g. query_graph- shaped with callers_of/callees_of patterns). Baseline: the IDE's find-references / go-to-definition, or grep -rn the symbol for callers and read the body for callees. Walk outward until reaching a test that exercises this path or a public entry point (HTTP handler, CLI command, message consumer, orchestration trigger).

1. Follow the full execution path through the suspected area — the entry point that triggers

the bug is often several hops from where the symptom surfaces. Accelerated: a flow query (e.g. get_flow-shaped) returns the whole path in one call. Baseline: read each hop in sequence, noting where state changes or a branch could diverge.

1. Check whether a recent change introduced it.

Accelerated: a change-detection call (e.g. detect_changes-shaped) flags recent risk-scored changes near the traced path. Baseline: git log -S'' --oneline -- or git blame the suspected lines — recent changes are the most common source of new issues, check this before assuming the bug is old.

1. Only now form a hypothesis, stated as "execution reaches line X via path Y, and the bug is

Z because of change W" — or "the bug predates commit V because no recent change touched this path". A hypothesis with no traced path behind it is a guess, not a diagnosis.

Gotchas

No environment-specific gotchas known.

Red flags — STOP

• Proposing a fix before step 2 has produced an actual caller/callee list
• Tracing only one direction — callers alone miss what the function itself calls into
• Treating "similar code exists elsewhere" as tracing this call chain
• Skipping step 4 — a large share of new bugs are yesterday's diff; the history check is cheap

relative to guessing

A diagnosis is not finished until it names the specific call path (caller → … → entry point) showing the bug is reachable, and states whether a specific recent change is implicated. "I think it's this function" with no traced path is not a diagnosis.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Arasz
• Source: Arasz/ai-badger
• License: MIT
• Homepage: https://github.com/Arasz/ai-badger

Install and usage instructions live in the source repository linked above.