karpathy-debugging

Diagnose software bugs through evidence-first root-cause analysis and minimal fixes.

Updated Jun 22, 2026
One-click install
npx skills add https://github.com/aicodepro/ai-agent-nexi --skill karpathy-debugging-aicodepro
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: karpathy-debugging
Source: https://github.com/aicodepro/ai-agent-nexi/tree/main/.opencode/skills/karpathy-debugging
Command: npx skills add https://github.com/aicodepro/ai-agent-nexi --skill karpathy-debugging-aicodepro

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Bug reports often describe symptoms without revealing causes, leading developers to apply speculative patches, null checks, and symptom-level fixes that mask the real defect. This Skill enforces a disciplined, evidence-first debugging methodology that finds and fixes root causes instead of symptoms. ## Core Features & Use Cases - Structured Debugging Method: A six-step process covering reproduction, full stack-trace reading, diffing against working cases, single-hypothesis testing, minimal root-cause fixes, and a circuit breaker after three failed hypotheses. - Anti-Pattern Detection: Flags common mistakes such as adding null checks without asking why, refactoring while fixing, and trusting fixes that merely hide symptoms. - Repo-Specific Gotchas: Documents Nexi-specific pitfalls, including the correct virtualenv interpreter, the three tool-registry lists (_TOOLS, ALLOWED_INTENTS, TOOL_INTENTS) that cause silent tool failures, and dynamic model selection via the model registry. - Use Case: When a tool in the Nexi assistant silently routes to chat instead of executing, use this Skill to systematically check all three registry lists before concluding the tool is broken. ## Quick Start Ask the assistant to apply the Karpathy debugging method to investigate why a specific bug or failing tool occurs before writing any fix.

Frequently Asked Questions about karpathy-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a bug when the cause is unknown?

Start by reproducing the bug reliably, then read the full stack trace and diff the broken path against a working case. Form one hypothesis at a time, name the test that would disprove it, and fix the root cause where all callers route through it.

How to fix a tool that silently fails in the Nexi assistant?

Check that the tool has entries in all three lists in engine/tool_registry.py: _TOOLS, ALLOWED_INTENTS, and TOOL_INTENTS. A missing entry causes silent routing to chat instead of an error, so verify all three before concluding the tool is broken.

What is root-cause debugging versus symptom patching?

Root-cause debugging traces data flow from input to the failure point and fixes the shared code path all callers use. Symptom patching adds guards like null checks at one call site without asking why the bad value exists, leaving the defect in place.

Why does Python give wrong answers when debugging Nexi?

Bare python resolves to a different virtualenv missing openwakeword, cv2, and sentence-transformers. Always use ./.venv/Scripts/python.exe so the interpreter has the correct dependencies installed.

When should I stop trying hypotheses and escalate a bug?

Stop after three failed hypotheses. The circuit-breaker rule says the bug is probably somewhere other than where you think, so escalate instead of trying a fourth variant of the same idea.