{"id":"6399a619-8510-445b-a075-93c93e5f715a","shortId":"Qezne7","kind":"skill","title":"systematic-debugging","tagline":"Root cause analysis for debugging. Use when bugs, test failures, or unexpected behavior have non-obvious causes, or after multiple fix attempts have failed.","description":"# Systematic Debugging\n\n**Core principle:** Find root cause before attempting fixes. Symptom fixes are failure.\n\n```\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\n```\n\n## Phase 1: Root Cause Investigation\n\n**BEFORE attempting ANY fix:**\n\n1. **Read Error Messages Carefully**\n   - Read stack traces completely\n   - Note line numbers, file paths, error codes\n   - Don't skip warnings\n\n2. **Reproduce Consistently**\n   - What are the exact steps?\n   - If not reproducible → gather more data, don't guess\n\n3. **Check Recent Changes**\n   - Git diff, recent commits\n   - New dependencies, config changes\n   - Environmental differences\n\n4. **Gather Evidence in Multi-Component Systems**\n\n   **WHEN system has multiple components (CI → build → signing, API → service → database):**\n\n   Add diagnostic instrumentation before proposing fixes:\n   ```\n   For EACH component boundary:\n     - Log what data enters/exits component\n     - Verify environment/config propagation\n     - Check state at each layer\n\n   Run once to gather evidence → analyze → identify failing component\n   ```\n\n   Example:\n   ```bash\n   # Layer 1: Workflow\n   echo \"=== Secrets available: ===\"\n   echo \"IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}\"\n\n   # Layer 2: Build script\n   env | grep IDENTITY || echo \"IDENTITY not in environment\"\n\n   # Layer 3: Signing\n   security find-identity -v\n   ```\n\n5. **Trace Data Flow**\n\n   See `references/root-cause-tracing.md` for backward tracing technique.\n\n   Quick version: Where does bad value originate? Trace up call chain until you find the source. Fix at source.\n\n## Phase 2: Pattern Analysis\n\n1. **Find Working Examples** - Similar working code in codebase\n2. **Compare Against References** - Read reference implementations COMPLETELY, don't skim\n3. **Identify Differences** - List every difference, don't assume \"that can't matter\"\n4. **Understand Dependencies** - Components, config, environment, assumptions\n\n## Phase 3: Hypothesis and Testing\n\n1. **Form Single Hypothesis** - \"I think X is root cause because Y\" - be specific\n2. **Test Minimally** - SMALLEST possible change, one variable at a time\n3. **Verify** - Worked → Phase 4. Didn't work → form NEW hypothesis, don't stack fixes\n4. **When You Don't Know** - Say so. Don't pretend.\n\n## Phase 4: Implementation\n\n1. **Create Failing Test Case**\n   - Use the `test-driven-development` skill\n   - MUST have before fixing\n\n2. **Implement Single Fix**\n   - ONE change at a time\n   - No \"while I'm here\" improvements\n\n3. **Verify Fix**\n   - Test passes? Other tests still pass? Issue resolved?\n\n4. **If Fix Doesn't Work**\n   - Count attempts\n   - If < 3: Return to Phase 1 with new information\n   - **If ≥ 3: Escalate (below)**\n\n## Escalation: 3+ Failed Fixes\n\n**Pattern indicating architectural problem:**\n- Each fix reveals new problems elsewhere\n- Fixes require massive refactoring\n- Shared state/coupling keeps surfacing\n\n**Action:** STOP. Question fundamentals:\n- Is this pattern fundamentally sound?\n- Are we continuing through inertia?\n- Refactor architecture vs. continue fixing symptoms?\n\n**Discuss with human partner before more fix attempts.** This is wrong architecture, not failed hypothesis.\n\n## Red Flags → STOP and Return to Phase 1\n\nIf you catch yourself thinking:\n- \"Quick fix for now, investigate later\"\n- \"Just try changing X\"\n- \"I'll skip the test\"\n- \"It's probably X\"\n- \"Pattern says X but I'll adapt it differently\"\n- Proposing solutions before tracing data flow\n- \"One more fix\" after 2+ failures\n\n## Human Signals You're Off Track\n\n- \"Is that not happening?\" → You assumed without verifying\n- \"Will it show us...?\" → You should have added evidence gathering\n- \"Stop guessing\" → You're proposing fixes without understanding\n- \"Ultrathink this\" → Question fundamentals\n- Frustrated \"We're stuck?\" → Your approach isn't working\n\n**Response:** Return to Phase 1.\n\n## Supporting Techniques\n\nReference files in `references/`:\n- **`root-cause-tracing.md`** - Trace bugs backward through call stack\n- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause\n- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling\n\nRelated skills:\n- **`test-driven-development`** - Creating failing test case (Phase 4)\n- **`verification-before-completion`** - Verify fix before claiming success","tags":["systematic","debugging","agent","skills","library","codingcossack","agent-framework","agent-skills","agent-system","agent-workflow","agentic-workflow","ai-agents"],"capabilities":["skill","source-codingcossack","skill-systematic-debugging","topic-agent-framework","topic-agent-skills","topic-agent-system","topic-agent-workflow","topic-agentic-workflow","topic-ai-agents","topic-anthropic","topic-claude","topic-claude-code","topic-claude-skills","topic-claude-skills-hub","topic-claude-skills-libary"],"categories":["agent-skills-library"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/CodingCossack/agent-skills-library/systematic-debugging","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add CodingCossack/agent-skills-library","source_repo":"https://github.com/CodingCossack/agent-skills-library","install_from":"skills.sh"}},"qualityScore":"0.458","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 17 github stars · SKILL.md body (4,319 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-04-23T07:01:19.681Z","embedding":null,"createdAt":"2026-04-18T23:06:39.775Z","updatedAt":"2026-04-23T07:01:19.681Z","lastSeenAt":"2026-04-23T07:01:19.681Z","tsv":"'1':51,59,164,228,273,327,382,454,549 '2':79,176,225,237,287,343,498 '3':96,188,248,269,298,358,378,387,391 '4':110,261,302,313,325,369,591 '5':195 'action':412 'ad':521 'adapt':485 'add':129,564 'analysi':6,227 'analyz':157 'api':126 'approach':541 'arbitrari':575 'architectur':396,427,443 'assum':256,511 'assumpt':267 'attempt':26,37,56,376,439 'avail':168 'backward':202,559 'bad':209 'bash':162 'behavior':16 'boundari':138 'bug':11,558 'build':124,177 'call':214,561 'care':63 'case':331,589 'catch':457 'caus':5,21,35,47,53,282,572 'chain':215 'chang':99,107,292,348,468 'check':97,147 'ci':123 'claim':599 'code':74,234 'codebas':236 'commit':103 'compar':238 'complet':67,244,595 'compon':116,122,137,143,160,264 'condit':578 'condition-based-waiting.md':573 'config':106,265 'consist':81 'continu':423,429 'core':31 'count':375 'creat':328,586 'data':92,141,197,492 'databas':128 'debug':3,8,30 'defense-in-depth.md':563 'depend':105,263 'develop':337,585 'diagnost':130 'didn':303 'diff':101 'differ':109,250,253,487 'discuss':432 'doesn':372 'driven':336,584 'echo':166,169,182 'elsewher':403 'enters/exits':142 'env':179 'environ':186,266 'environment':108 'environment/config':145 'error':61,73 'escal':388,390 'everi':252 'evid':112,156,522 'exact':85 'exampl':161,231 'fail':28,159,329,392,445,587 'failur':13,42,499 'file':71,553 'find':33,192,218,229,570 'find-ident':191 'first':49 'fix':25,38,40,44,58,134,221,312,342,346,360,371,393,399,404,430,438,461,496,529,597 'flag':448 'flow':198,493 'form':274,306 'frustrat':536 'fundament':415,419,535 'gather':90,111,155,523 'git':100 'grep':180 'guess':95,525 'happen':509 'human':434,500 'hypothesi':270,276,308,446 'ident':170,171,173,181,183,193 'identifi':158,249 'implement':243,326,344 'improv':357 'indic':395 'inertia':425 'inform':385 'instrument':131 'investig':48,54,464 'isn':542 'issu':367 'keep':410 'know':318 'later':465 'layer':151,163,175,187,568 'line':69 'list':251 'll':471,484 'log':139 'm':355 'massiv':406 'matter':260 'messag':62 'minim':289 'multi':115 'multi-compon':114 'multipl':24,121,567 'must':339 'new':104,307,384,401 'non':19 'non-obvi':18 'note':68 'number':70 'obvious':20 'one':293,347,494 'origin':211 'partner':435 'pass':362,366 'path':72 'pattern':226,394,418,479 'phase':50,224,268,301,324,381,453,548,590 'poll':579 'possibl':291 'pretend':323 'principl':32 'probabl':477 'problem':397,402 'propag':146 'propos':133,488,528 'question':414,534 'quick':205,460 're':503,527,538 'read':60,64,241 'recent':98,102 'red':447 'refactor':407,426 'refer':240,242,552,555 'references/root-cause-tracing.md':200 'relat':580 'replac':574 'reproduc':80,89 'requir':405 'resolv':368 'respons':545 'return':379,451,546 'reveal':400 'root':4,34,46,52,281,571 'root-cause-tracing.md':556 'run':152 'say':319,480 'script':178 'secret':167 'secur':190 'see':199 'servic':127 'set':172 'share':408 'show':516 'sign':125,189 'signal':501 'similar':232 'singl':275,345 'skill':338,581 'skill-systematic-debugging' 'skim':247 'skip':77,472 'smallest':290 'solut':489 'sound':420 'sourc':220,223 'source-codingcossack' 'specif':286 'stack':65,311,562 'state':148 'state/coupling':409 'step':86 'still':365 'stop':413,449,524 'stuck':539 'success':600 'support':550 'surfac':411 'symptom':39,431 'system':117,119 'systemat':2,29 'systematic-debug':1 'techniqu':204,551 'test':12,272,288,330,335,361,364,474,583,588 'test-driven-develop':334,582 'think':278,459 'time':297,351 'timeout':576 'topic-agent-framework' 'topic-agent-skills' 'topic-agent-system' 'topic-agent-workflow' 'topic-agentic-workflow' 'topic-ai-agents' 'topic-anthropic' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-claude-skills-hub' 'topic-claude-skills-libary' 'trace':66,196,203,212,491,557 'track':505 'tri':467 'ultrathink':532 'understand':262,531 'unexpect':15 'unset':174 'us':517 'use':9,332 'v':194 'valid':565 'valu':210 'variabl':294 'verif':593 'verifi':144,299,359,513,596 'verification-before-complet':592 'version':206 'vs':428 'warn':78 'without':45,512,530 'work':230,233,300,305,374,544 'workflow':165 'wrong':442 'x':279,469,478,481 'y':284","prices":[{"id":"b9b4bf60-13a7-4674-a89e-b395e9e3315b","listingId":"6399a619-8510-445b-a075-93c93e5f715a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"CodingCossack","category":"agent-skills-library","install_from":"skills.sh"},"createdAt":"2026-04-18T23:06:39.775Z"}],"sources":[{"listingId":"6399a619-8510-445b-a075-93c93e5f715a","source":"github","sourceId":"CodingCossack/agent-skills-library/systematic-debugging","sourceUrl":"https://github.com/CodingCossack/agent-skills-library/tree/main/skills/systematic-debugging","isPrimary":false,"firstSeenAt":"2026-04-18T23:06:39.775Z","lastSeenAt":"2026-04-23T07:01:19.681Z"}],"details":{"listingId":"6399a619-8510-445b-a075-93c93e5f715a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"CodingCossack","slug":"systematic-debugging","github":{"repo":"CodingCossack/agent-skills-library","stars":17,"topics":["agent-framework","agent-skills","agent-system","agent-workflow","agentic-workflow","ai-agents","anthropic","claude","claude-code","claude-skills","claude-skills-hub","claude-skills-libary","code-review","codex","context-engineering","debugging","developer-workflow"],"license":null,"html_url":"https://github.com/CodingCossack/agent-skills-library","pushed_at":"2026-01-03T20:02:38Z","description":"Coding agent skills library for programming workflows | Claude Skills, Codex Skills | Forked from obra/superpower","skill_md_sha":"18de8601a2cf2c4cdb077de5784e2fa2e5ada5b9","skill_md_path":"skills/systematic-debugging/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/CodingCossack/agent-skills-library/tree/main/skills/systematic-debugging"},"layout":"multi","source":"github","category":"agent-skills-library","frontmatter":{"name":"systematic-debugging","description":"Root cause analysis for debugging. Use when bugs, test failures, or unexpected behavior have non-obvious causes, or after multiple fix attempts have failed."},"skills_sh_url":"https://skills.sh/CodingCossack/agent-skills-library/systematic-debugging"},"updatedAt":"2026-04-23T07:01:19.681Z"}}