{"id":"4b2b6c47-0b2a-4636-bd15-bcf6744a7ba9","shortId":"Ec9mAx","kind":"skill","title":"code-debug","tagline":"Systematic debugging workflow and techniques. Use when something is broken, not working as expected, or throwing errors. Covers reproduction, isolation, hypothesis formation, fix implementation, and verification. Also triggers on \"why does X fail\", \"debug this\", \"this is broken\",","description":"# Code Debug\n\nSystematic debugging workflow to find and fix bugs efficiently. Never guess — always\nnarrow down the problem through systematic elimination.\n\n## The Debugging Mindset\n\n| Bad | Good |\n|-----|------|\n| \"I think it's...\" | \"Let me verify...\" |\n| Changing random things | Binary search narrowing |\n| Hoping it'll work | Verifying each hypothesis |\n| Moving on after it works | Adding regression test |\n\n## The Five-Step Workflow\n\n### Step 1: Reproduce\n\nCreate the smallest possible reproduction case.\n\n**Questions to answer:**\n- What exactly triggers the bug?\n- Can I make it happen on demand?\n- What's the minimal input that causes it?\n\n**Techniques:**\n- Extract exact steps from bug report\n- Remove unrelated factors\n- Create a minimal test case\n\n**Output:** \"I can reproduce the bug by [exact steps].\"\n\n---\n\n### Step 2: Isolate\n\nNarrow down where the bug lives using binary search.\n\n**Binary search strategies:**\n- Comment out half the code → does it still fail?\n- Isolate by layer: is it the UI, service, or data layer?\n- Isolate by file: which file contains the bug?\n- Isolate by function: which function causes the issue?\n\n**Git bisect** (for regression bugs):\n```bash\ngit bisect start\ngit bisect bad  # current commit is broken\ngit bisect good <last-working-commit>\n# Run tests, mark good/bad\ngit bisect reset  # done\n```\n\n**Output:** \"The bug is in [specific file/function/component].\"\n\n---\n\n### Step 3: Form Hypothesis\n\nMake a testable guess about the root cause.\n\n**Good hypothesis:**\n- Specific: \"The user ID is undefined because...\"\n- Testable: Can verify with a test or log\n- Grounded: Based on evidence, not guess\n\n**Questions to ask:**\n- Why does this happen?\n- What are the preconditions?\n- What's the actual vs expected behavior?\n- What changed recently?\n\n**Output:** \"I hypothesize that [root cause] because [evidence].\"\n\n---\n\n### Step 4: Fix\n\nImplement the fix based on your hypothesis.\n\n**Rules:**\n- Make minimal changes\n- Don't refactor while fixing (separate concerns)\n- Write failing test first if possible\n- Consider edge cases\n\n**Fix patterns:**\n- **Missing value** → Add null check or default\n- **Wrong value** → Correct the logic\n- **Exception** → Handle the error case\n- **Logic error** → Fix the condition\n\n**Output:** \"Fix applied: [brief description].\"\n\n---\n\n### Step 5: Verify\n\nConfirm the fix works and doesn't break anything.\n\n**Verification steps:**\n1. Run the reproduction case → should pass now\n2. Run related tests → should pass\n3. Run full test suite → should pass\n4. Add regression test → prevents future breakage\n\n**Output:** \"Fix verified. Tests passing. Regression test added.\"\n\n---\n\n## Debugging Techniques\n\n### Print Debugging\n\nQuick and dirty, but sometimes the fastest way.\n\n**When to use:**\n- Quick checks in development\n- When debugger isn't available\n- Understanding flow in unfamiliar code\n\n**Best practices:**\n- Print at entry/exit of functions\n- Print variable values at key points\n- Remove print statements before committing\n- Consider structured logging instead\n\n### Debugger\n\nMore powerful than print debugging.\n\n**When to use:**\n- Complex state to inspect\n- Stepping through logic\n- Evaluating expressions in context\n\n**See references/language-tools.md for language-specific debugger commands.**\n\n### Logging\n\nBetter than print for production issues.\n\n**Strategies:**\n- Add context: request ID, user ID, correlation IDs\n- Log at appropriate levels: DEBUG, INFO, WARN, ERROR\n- Don't log sensitive data\n- Structured logging (JSON) for easier parsing\n\n**See references/techniques.md for logging patterns.**\n\n### Binary Search\n\nHalving the search space.\n\n**Strategies:**\n- Comment out code blocks\n- Test with half the data\n- Compare working vs broken configurations\n- Git bisect for regressions\n\n### Rubber Ducking\n\nExplain the problem out loud (or to a rubber duck).\n\n**Process:**\n1. Describe the problem in detail\n2. Explain what you expect to happen\n3. Explain what's actually happening\n4. Often the solution becomes clear mid-explanation\n\n---\n\n## Common Bug Patterns\n\n### Null/Undefined Errors\n\n**Symptoms:** Cannot read property X of undefined\n\n**Debug approach:**\n1. Find where the value becomes undefined\n2. Trace back where it should come from\n3. Add guard or fix source\n\n**Fix patterns:**\n```javascript\n// Before\nconst name = user.profile.name;\n\n// After\nconst name = user?.profile?.name ?? 'Unknown';\n// or\nif (!user?.profile) return;\nconst name = user.profile.name;\n```\n\n### Race Conditions\n\n**Symptoms:** Intermittent failures, flaky tests\n\n**Debug approach:**\n1. Identify async operations\n2. Find timing dependencies\n3. Add delays or force ordering\n\n**Fix patterns:**\n- Use async/await properly\n- Add proper synchronization\n- Consider immutable state\n\n### Logic Errors\n\n**Symptoms:** Wrong output, wrong behavior\n\n**Debug approach:**\n1. Trace through the logic manually\n2. Compare expected vs actual at each step\n3. Find the first step that diverges\n\n**Fix patterns:**\n- Fix the condition\n- Correct the calculation\n- Update the state correctly\n\n### Performance Issues\n\n**Symptoms:** Slow, memory leaks, timeouts\n\n**Debug approach:**\n1. Measure first (don't guess)\n2. Identify hot paths\n3. Optimize the bottleneck\n\n**See code-perf skill for detailed performance debugging.**\n\n---\n\n## Skill Loading\n\nCheck available skills for additional debugging support:\n\n- If dealing with performance issues → load code-perf\n- If security vulnerability suspected → load code-security\n- If debugging tests → load oracle-testing\n\n---\n\n## Output Format\n\nAfter each debugging session, summarize:\n\n```\n## Debug Summary\n\n**Problem:** [One sentence]\n**Root Cause:** [What actually was wrong]\n**Fix:** [How you fixed it]\n**Verification:** [Test results]\n**Prevention:** [Regression test added?]\n```\n\nThis helps future-you understand what happened.","tags":["code","debug","atelier","martinffx","agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex","codex-skill"],"capabilities":["skill","source-martinffx","skill-code-debug","topic-agent-skills","topic-agentic-coding","topic-anthropic","topic-claude-code","topic-claude-skills","topic-code-review","topic-codex","topic-codex-skill","topic-opencode","topic-prompt-engineering","topic-sdd","topic-spec-driven-development"],"categories":["atelier"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/martinffx/atelier/code-debug","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add martinffx/atelier","source_repo":"https://github.com/martinffx/atelier","install_from":"skills.sh"}},"qualityScore":"0.461","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 23 github stars · SKILL.md body (5,800 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:05:21.843Z","embedding":null,"createdAt":"2026-05-10T07:03:10.849Z","updatedAt":"2026-05-18T19:05:21.843Z","lastSeenAt":"2026-05-18T19:05:21.843Z","tsv":"'1':102,379,572,614,666,700,742 '2':158,387,578,621,670,706,748 '3':243,393,585,629,674,714,752 '4':307,400,591 '5':366 'actual':291,589,710,813 'ad':93,414,827 'add':340,401,502,630,675,685 'addit':771 'also':30 'alway':55 'answer':112 'anyth':376 'appli':362 'approach':613,665,699,741 'appropri':512 'ask':279 'async':668 'async/await':683 'avail':438,768 'back':623 'bad':66,219 'base':272,312 'bash':213 'becom':595,619 'behavior':294,697 'best':444 'better':495 'binari':78,167,169,534 'bisect':209,215,218,225,232,556 'block':544 'bottleneck':755 'break':375 'breakag':406 'brief':363 'broken':13,41,223,553 'bug':51,117,138,153,164,199,212,237,601 'calcul':728 'cannot':606 'case':109,147,335,354,383 'caus':131,205,253,303,811 'chang':75,296,319 'check':342,431,767 'clear':596 'code':2,42,176,443,543,758,781,789 'code-debug':1 'code-perf':757,780 'code-secur':788 'come':627 'command':493 'comment':172,541 'commit':221,461 'common':600 'compar':550,707 'complex':475 'concern':326 'condit':359,658,725 'configur':554 'confirm':368 'consid':333,462,688 'const':639,643,654 'contain':197 'context':485,503 'correct':347,726,732 'correl':508 'cover':21 'creat':104,143 'current':220 'data':190,522,549 'deal':775 'debug':3,5,37,43,45,64,415,418,471,514,612,664,698,740,764,772,792,802,805 'debugg':435,466,492 'default':344 'delay':676 'demand':124 'depend':673 'describ':573 'descript':364 'detail':577,762 'develop':433 'dirti':421 'diverg':720 'doesn':373 'done':234 'duck':560,570 'easier':527 'edg':334 'effici':52 'elimin':62 'entry/exit':448 'error':20,353,356,517,604,692 'evalu':482 'evid':274,305 'exact':114,135,155 'except':350 'expect':17,293,582,708 'explain':561,579,586 'explan':599 'express':483 'extract':134 'factor':142 'fail':36,180,328 'failur':661 'fastest':425 'file':194,196 'file/function/component':241 'find':48,615,671,715 'first':330,717,744 'five':98 'five-step':97 'fix':26,50,308,311,324,336,357,361,370,408,633,635,680,721,723,816,819 'flaki':662 'flow':440 'forc':678 'form':244 'format':25,799 'full':395 'function':202,204,450 'futur':405,831 'future-you':830 'git':208,214,217,224,231,555 'good':67,226,254 'good/bad':230 'ground':271 'guard':631 'guess':54,249,276,747 'half':174,547 'halv':536 'handl':351 'happen':122,283,584,590,835 'help':829 'hope':81 'hot':750 'hypothes':300 'hypothesi':24,87,245,255,315 'id':259,505,507,509 'identifi':667,749 'immut':689 'implement':27,309 'info':515 'input':129 'inspect':478 'instead':465 'intermitt':660 'isn':436 'isol':23,159,181,192,200 'issu':207,500,734,778 'javascript':637 'json':525 'key':455 'languag':490 'language-specif':489 'layer':183,191 'leak':738 'let':72 'level':513 'live':165 'll':83 'load':766,779,787,794 'log':270,464,494,510,520,524,532 'logic':349,355,481,691,704 'loud':565 'make':120,246,317 'manual':705 'mark':229 'measur':743 'memori':737 'mid':598 'mid-explan':597 'mindset':65 'minim':128,145,318 'miss':338 'move':88 'name':640,644,647,655 'narrow':56,80,160 'never':53 'null':341 'null/undefined':603 'often':592 'one':808 'oper':669 'optim':753 'oracl':796 'oracle-test':795 'order':679 'output':148,235,298,360,407,695,798 'pars':528 'pass':385,392,399,411 'path':751 'pattern':337,533,602,636,681,722 'perf':759,782 'perform':733,763,777 'point':456 'possibl':107,332 'power':468 'practic':445 'precondit':287 'prevent':404,824 'print':417,446,451,458,470,497 'problem':59,563,575,807 'process':571 'product':499 'profil':646,652 'proper':684,686 'properti':608 'question':110,277 'quick':419,430 'race':657 'random':76 'read':607 'recent':297 'refactor':322 'references/language-tools.md':487 'references/techniques.md':530 'regress':94,211,402,412,558,825 'relat':389 'remov':140,457 'report':139 'reproduc':103,151 'reproduct':22,108,382 'request':504 'reset':233 'result':823 'return':653 'root':252,302,810 'rubber':559,569 'rule':316 'run':227,380,388,394 'search':79,168,170,535,538 'secur':784,790 'see':486,529,756 'sensit':521 'sentenc':809 'separ':325 'servic':188 'session':803 'skill':760,765,769 'skill-code-debug' 'slow':736 'smallest':106 'solut':594 'someth':11 'sometim':423 'sourc':634 'source-martinffx' 'space':539 'specif':240,256,491 'start':216 'state':476,690,731 'statement':459 'step':99,101,136,156,157,242,306,365,378,479,713,718 'still':179 'strategi':171,501,540 'structur':463,523 'suit':397 'summar':804 'summari':806 'support':773 'suspect':786 'symptom':605,659,693,735 'synchron':687 'systemat':4,44,61 'techniqu':8,133,416 'test':95,146,228,268,329,390,396,403,410,413,545,663,793,797,822,826 'testabl':248,263 'thing':77 'think':69 'throw':19 'time':672 'timeout':739 'topic-agent-skills' 'topic-agentic-coding' 'topic-anthropic' 'topic-claude-code' 'topic-claude-skills' 'topic-code-review' 'topic-codex' 'topic-codex-skill' 'topic-opencode' 'topic-prompt-engineering' 'topic-sdd' 'topic-spec-driven-development' 'trace':622,701 'trigger':31,115 'ui':187 'undefin':261,611,620 'understand':439,833 'unfamiliar':442 'unknown':648 'unrel':141 'updat':729 'use':9,166,429,474,682 'user':258,506,645,651 'user.profile.name':641,656 'valu':339,346,453,618 'variabl':452 'verif':29,377,821 'verifi':74,85,265,367,409 'vs':292,552,709 'vulner':785 'warn':516 'way':426 'work':15,84,92,371,551 'workflow':6,46,100 'write':327 'wrong':345,694,696,815 'x':35,609","prices":[{"id":"5ba822f2-7fe8-451f-a94f-34f8dac22fe0","listingId":"4b2b6c47-0b2a-4636-bd15-bcf6744a7ba9","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"martinffx","category":"atelier","install_from":"skills.sh"},"createdAt":"2026-05-10T07:03:10.849Z"}],"sources":[{"listingId":"4b2b6c47-0b2a-4636-bd15-bcf6744a7ba9","source":"github","sourceId":"martinffx/atelier/code-debug","sourceUrl":"https://github.com/martinffx/atelier/tree/main/skills/code-debug","isPrimary":false,"firstSeenAt":"2026-05-10T07:03:10.849Z","lastSeenAt":"2026-05-18T19:05:21.843Z"}],"details":{"listingId":"4b2b6c47-0b2a-4636-bd15-bcf6744a7ba9","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"martinffx","slug":"code-debug","github":{"repo":"martinffx/atelier","stars":23,"topics":["agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex","codex-skill","opencode","prompt-engineering","sdd","spec-driven-development"],"license":"mit","html_url":"https://github.com/martinffx/atelier","pushed_at":"2026-05-18T06:56:45Z","description":"An atelier for Opencode, Claude Code, and other coding agents: spec-driven workflows, deep thinking, and code quality.","skill_md_sha":"7f3128ccafa7e23b2290a64ad625cca5b14f7541","skill_md_path":"skills/code-debug/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/martinffx/atelier/tree/main/skills/code-debug"},"layout":"multi","source":"github","category":"atelier","frontmatter":{"name":"code-debug","description":"Systematic debugging workflow and techniques. Use when something is broken, not working as expected, or throwing errors. Covers reproduction, isolation, hypothesis formation, fix implementation, and verification. Also triggers on \"why does X fail\", \"debug this\", \"this is broken\", or when encountering errors or unexpected behavior."},"skills_sh_url":"https://skills.sh/martinffx/atelier/code-debug"},"updatedAt":"2026-05-18T19:05:21.843Z"}}