codebase-debugging

A codebase troubleshooting guide for locating the part of a software project most likely responsible for an error, regression, crash, flaky test, or unexpected result.

In plain words
What is it for?
Use it to investigate why something broke, trace where an exception starts, find likely causes of a regression, or identify what changed around a failing area.
Why use it?
It narrows the search using project notes about busy dependencies, recent changes, and files that often change together, so you do not need to reread the whole project.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/dhevenddra/forensic-deepdive/codebase-debugging
Any agent
npx skills add Dhevenddra/forensic-deepdive --skill codebase-debugging
Clone the repo
git clone --depth 1 https://github.com/Dhevenddra/forensic-deepdive

Made for: Claude Code, Codex.

Per session 117 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 516 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00117 $0.00516
Opus 5 $0.00059 $0.00258
Sonnet 5 $0.00023 $0.00103
Haiku 4.5 $0.00012 $0.00052

Measured yesterday against content hash c0ff486bc4b1, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

codebase-debugging scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

tests/fixtures/prior_release/v0_8_0/.claude/skills/codebase-debugging/SKILL.md · 35 lines

What it actually says

Codebase debugging

Triangulate a bug to its likely region without re-reading the whole repo.

When to use

  • User reports an error / regression / flake / unexpected output.
  • Question shape: 'why is X broken', 'where does this exception originate', 'what changed that could cause this', 'this used to work'.

When NOT to use

  • User is orienting / learning, not fixing → codebase-exploring.
  • User is planning a refactor → codebase-refactoring.
  • Question is about correctness of a single function → just read it.

How to answer

  1. Always read docs/codebase/AGENT_BRIEF.md first — the never/always rules often pin the load-bearing call site.
  2. Match the question shape:
Question shape Artifact
'What are the hot spots / where is most activity' docs/codebase/HOTPATHS.md (Dependency hot spots)
'What changed recently around X' docs/codebase/ARCHAEOLOGY.md (Recent commits, churn)
'What's the defect-proximity neighborhood' docs/codebase/ARCHAEOLOGY.md
'What co-changes with this file' docs/codebase/HOTPATHS.md (Co-change clusters)
  1. If forensic serve is running, call archaeology(file_or_symbol) for the full git-history view in one call — recent commits, dominant author, defect proximity, co-change cluster.

Citation rule

Cite docs/codebase/HOTPATHS.md:42 or docs/codebase/ARCHAEOLOGY.md:78. If a graph-mode HOTPATHS shows AMBIGUOUS-confidence edges around the suspect symbol, surface that — agents and humans both need to know the resolver wasn't sure.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 35 lines · 117 tokens per session scan A c0ff486bc4b1

Subscribe to this mod's changes

codebase-debugging is a skill published in the GitHub repository Dhevenddra/forensic-deepdive (2 stars, last pushed 16d ago), licensed Apache-2.0. It adds 117 tokens to every session and 516 once invoked, about $0.0006 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

mistakes

List past mistakes engram has learned in this project — failures, regressions, broken assumptions. Use before starting a non-trivial change to surface relevant prior failures, or when debugging to check if this issue has been seen before.

NickCirv/engram · 46 tokens

query

Query engram's local knowledge graph for structural context — function calls, imports, type relationships, mistake history, ADRs. Use when the user asks "how does X work in this project", "what calls Y", "where is Z used", or any structural question that doesn't need file content.

NickCirv/engram · 60 tokens

chatcrystal-task-writeback

Write reusable ChatCrystal task memories after substantive work completes. Use when implementation or debugging produced a durable fix, pitfall, pattern, or decision worth preserving, and when the environment can either persist it through writetaskmemory or emit a structured memory candidate for later save.

ZengLiangYi/ChatCrystal · 62 tokens

chatcrystal-debug-recall

Recall ChatCrystal memories for debugging tasks involving failing tests, compiler errors, runtime exceptions, dependency issues, environment breakage, or performance regressions. Use when historical root causes, fixes, or pitfalls may accelerate diagnosis before proposing a fix.

ZengLiangYi/ChatCrystal · 54 tokens

chatcrystal-task-recall

Recall project-first and global-supplement ChatCrystal memories before substantive implementation, refactoring, migration, configuration, investigation, or optimization work. Use when the task is non-trivial, has repository or project context, and prior fixes, decisions, pitfalls, or reusable patterns may change the…

ZengLiangYi/ChatCrystal · 66 tokens

slm-recall

Search and retrieve facts, decisions, and past context from SuperLocalMemory. Use when the user asks to recall, find, search, or "what did we decide/say about X". Triggers multi-channel semantic retrieval with reranking; always call before storing anything new.

qualixar/superlocalmemory · 60 tokens