{"id":"2ed9cff8-50f9-4576-89bb-93a3d9a47270","shortId":"pT8fhs","kind":"skill","title":"systematic-debugging","tagline":"Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes","description":"# Systematic Debugging\n\n## Overview\n\nRandom fixes waste time and create new bugs. Quick patches mask underlying issues.\n\n**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.\n\n**Violating the letter of this process is violating the spirit of debugging.**\n\n## The Iron Law\n\n```\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\n```\n\nIf you haven't completed Phase 1, you cannot propose fixes.\n\n## When to Use\nUse for ANY technical issue:\n- Test failures\n- Bugs in production\n- Unexpected behavior\n- Performance problems\n- Build failures\n- Integration issues\n\n**Use this ESPECIALLY when:**\n- Under time pressure (emergencies make guessing tempting)\n- \"Just one quick fix\" seems obvious\n- You've already tried multiple fixes\n- Previous fix didn't work\n- You don't fully understand the issue\n\n**Don't skip when:**\n- Issue seems simple (simple bugs have root causes too)\n- You're in a hurry (rushing guarantees rework)\n- Manager wants it fixed NOW (systematic is faster than thrashing)\n\n## The Four Phases\n\nYou MUST complete each phase before proceeding to the next.\n\n### Phase 1: Root Cause Investigation\n\n**BEFORE attempting ANY fix:**\n\n1. **Read Error Messages Carefully**\n   - Don't skip past errors or warnings\n   - They often contain the exact solution\n   - Read stack traces completely\n   - Note line numbers, file paths, error codes\n\n2. **Reproduce Consistently**\n   - Can you trigger it reliably?\n   - What are the exact steps?\n   - Does it happen every time?\n   - If not reproducible → gather more data, don't guess\n\n3. **Check Recent Changes**\n   - What changed that could cause this?\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   **BEFORE proposing fixes, add diagnostic instrumentation:**\n   ```\n   For EACH component boundary:\n     - Log what data enters component\n     - Log what data exits component\n     - Verify environment/config propagation\n     - Check state at each layer\n\n   Run once to gather evidence showing WHERE it breaks\n   THEN analyze evidence to identify failing component\n   THEN investigate that specific component\n   ```\n\n   **Example (multi-layer system):**\n   ```bash\n   # Layer 1: Workflow\n   echo \"=== Secrets available in workflow: ===\"\n   echo \"IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}\"\n\n   # Layer 2: Build script\n   echo \"=== Env vars in build script: ===\"\n   env | grep IDENTITY || echo \"IDENTITY not in environment\"\n\n   # Layer 3: Signing script\n   echo \"=== Keychain state: ===\"\n   security list-keychains\n   security find-identity -v\n\n   # Layer 4: Actual signing\n   codesign --sign \"$IDENTITY\" --verbose=4 \"$APP\"\n   ```\n\n   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)\n\n5. **Trace Data Flow**\n\n   **WHEN error is deep in call stack:**\n\n   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.\n\n   **Quick version:**\n   - Where does bad value originate?\n   - What called this with bad value?\n   - Keep tracing up until you find the source\n   - Fix at source, not at symptom\n\n### Phase 2: Pattern Analysis\n\n**Find the pattern before fixing:**\n\n1. **Find Working Examples**\n   - Locate similar working code in same codebase\n   - What works that's similar to what's broken?\n\n2. **Compare Against References**\n   - If implementing pattern, read reference implementation COMPLETELY\n   - Don't skim - read every line\n   - Understand the pattern fully before applying\n\n3. **Identify Differences**\n   - What's different between working and broken?\n   - List every difference, however small\n   - Don't assume \"that can't matter\"\n\n4. **Understand Dependencies**\n   - What other components does this need?\n   - What settings, config, environment?\n   - What assumptions does it make?\n\n### Phase 3: Hypothesis and Testing\n\n**Scientific method:**\n\n1. **Form Single Hypothesis**\n   - State clearly: \"I think X is the root cause because Y\"\n   - Write it down\n   - Be specific, not vague\n\n2. **Test Minimally**\n   - Make the SMALLEST possible change to test hypothesis\n   - One variable at a time\n   - Don't fix multiple things at once\n\n3. **Verify Before Continuing**\n   - Did it work? Yes → Phase 4\n   - Didn't work? Form NEW hypothesis\n   - DON'T add more fixes on top\n\n4. **When You Don't Know**\n   - Say \"I don't understand X\"\n   - Don't pretend to know\n   - Ask for help\n   - Research more\n\n### Phase 4: Implementation\n\n**Fix the root cause, not the symptom:**\n\n1. **Create Failing Test Case**\n   - Simplest possible reproduction\n   - Automated test if possible\n   - One-off test script if no framework\n   - MUST have before fixing\n   - Use the `superpowers:test-driven-development` skill for writing proper failing tests\n\n2. **Implement Single Fix**\n   - Address the root cause identified\n   - ONE change at a time\n   - No \"while I'm here\" improvements\n   - No bundled refactoring\n\n3. **Verify Fix**\n   - Test passes now?\n   - No other tests broken?\n   - Issue actually resolved?\n\n4. **If Fix Doesn't Work**\n   - STOP\n   - Count: How many fixes have you tried?\n   - If < 3: Return to Phase 1, re-analyze with new information\n   - **If ≥ 3: STOP and question the architecture (step 5 below)**\n   - DON'T attempt Fix #4 without architectural discussion\n\n5. **If 3+ Fixes Failed: Question Architecture**\n\n   **Pattern indicating architectural problem:**\n   - Each fix reveals new shared state/coupling/problem in different place\n   - Fixes require \"massive refactoring\" to implement\n   - Each fix creates new symptoms elsewhere\n\n   **STOP and question fundamentals:**\n   - Is this pattern fundamentally sound?\n   - Are we \"sticking with it through sheer inertia\"?\n   - Should we refactor architecture vs. continue fixing symptoms?\n\n   **Discuss with your human partner before attempting more fixes**\n\n   This is NOT a failed hypothesis - this is a wrong architecture.\n\n## Red Flags - STOP and Follow Process\n\nIf you catch yourself thinking:\n- \"Quick fix for now, investigate later\"\n- \"Just try changing X and see if it works\"\n- \"Add multiple changes, run tests\"\n- \"Skip the test, I'll manually verify\"\n- \"It's probably X, let me fix that\"\n- \"I don't fully understand but this might work\"\n- \"Pattern says X but I'll adapt it differently\"\n- \"Here are the main problems: [lists fixes without investigation]\"\n- Proposing solutions before tracing data flow\n- **\"One more fix attempt\" (when already tried 2+)**\n- **Each fix reveals new problem in different place**\n\n**ALL of these mean: STOP. Return to Phase 1.**\n\n**If 3+ fixes failed:** Question the architecture (see Phase 4.5)\n\n## your human partner's Signals You're Doing It Wrong\n\n**Watch for these redirections:**\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, not just symptoms\n- \"We're stuck?\" (frustrated) - Your approach isn't working\n\n**When you see these:** STOP. Return to Phase 1.\n\n## Common Rationalizations\n\n| Excuse | Reality |\n|--------|---------|\n| \"Issue is simple, don't need process\" | Simple issues have root causes too. Process is fast for simple bugs. |\n| \"Emergency, no time for process\" | Systematic debugging is FASTER than guess-and-check thrashing. |\n| \"Just try this first, then investigate\" | First fix sets the pattern. Do it right from the start. |\n| \"I'll write test after confirming fix works\" | Untested fixes don't stick. Test first proves it. |\n| \"Multiple fixes at once saves time\" | Can't isolate what worked. Causes new bugs. |\n| \"Reference too long, I'll adapt the pattern\" | Partial understanding guarantees bugs. Read it completely. |\n| \"I see the problem, let me fix it\" | Seeing symptoms ≠ understanding root cause. |\n| \"One more fix attempt\" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |\n\n## Quick Reference\n\n| Phase | Key Activities | Success Criteria |\n|-------|---------------|------------------|\n| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |\n| **2. Pattern** | Find working examples, compare | Identify differences |\n| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |\n| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |\n\n## When Process Reveals \"No Root Cause\"\n\nIf systematic investigation reveals issue is truly environmental, timing-dependent, or external:\n\n1. You've completed the process\n2. Document what you investigated\n3. Implement appropriate handling (retry, timeout, error message)\n4. Add monitoring/logging for future investigation\n\n**But:** 95% of \"no root cause\" cases are incomplete investigation.\n\n## Supporting Techniques\n\nThese techniques are part of systematic debugging and available in this directory:\n\n- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger\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\n**Related skills:**\n- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)\n- **superpowers:verification-before-completion** - Verify fix worked before claiming success\n\n## Real-World Impact\n\nFrom debugging sessions:\n- Systematic approach: 15-30 minutes to fix\n- Random fixes approach: 2-3 hours of thrashing\n- First-time fix rate: 95% vs 40%\n- New bugs introduced: Near zero vs common\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.","tags":["systematic","debugging","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows"],"capabilities":["skill","source-sickn33","skill-systematic-debugging","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/systematic-debugging","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34460 github stars · SKILL.md body (10,036 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-22T06:51:57.972Z","embedding":null,"createdAt":"2026-04-18T21:45:46.953Z","updatedAt":"2026-04-22T06:51:57.972Z","lastSeenAt":"2026-04-22T06:51:57.972Z","tsv":"'-3':1347 '-30':1339 '1':74,180,188,339,463,553,653,745,950,1025,1164,1225,1317 '15':1338 '2':217,353,455,483,575,690,933,1145,1178,1231,1346 '3':244,371,506,547,598,713,741,753,772,952,1147,1186,1236 '4':264,387,394,528,607,621,644,726,766,1196,1244,1315 '4.5':960 '40':1358 '5':405,760,770 '95':1251,1356 'activ':1161 'actual':388,724 'ad':990 'adapt':908,1117 'add':286,616,873,1245,1286 'address':694 'alreadi':119,931 'alway':35 'analysi':457 'analyz':321,748 'api':280 'app':395 'appli':505 'approach':1013,1337,1345 'appropri':1238 'arbitrari':1297 'architectur':758,768,776,779,822,846,957,1149 'ask':638,1399 'assum':523,980 'assumpt':542 'attempt':40,185,764,833,929,1143 'autom':661 'avail':343,1270 'backward':424,1277 'bad':431,438 'bash':337 'behavior':13,93 'boundari':292,1407 'break':319 'broken':482,515,722 'bug':8,27,89,143,1048,1111,1123,1202,1276,1360 'build':96,278,354,360,404 'bundl':711 'call':414,435,1279 'cannot':76 'care':192 'case':657,1256,1313 'catch':855 'caus':38,65,146,182,252,565,649,697,1041,1109,1139,1166,1211,1255,1294 'chang':247,249,261,582,700,866,875,1171 'check':245,306,1062,1170 'ci':277 'claim':1327 'clarif':1401 'clear':558,1374 'code':216,470 'codebas':473 'codesign':390 'commit':257 'common':1026,1365 'compar':484,1183 'complet':72,171,209,423,493,1126,1228,1322 'compon':270,276,291,297,302,326,331,533 'condit':1300 'condition-based-waiting.md':1295 'config':260,539 'confirm':1086,1192 'consist':219 'contain':202 'continu':601,824 'core':33 'could':251 'count':733 'creat':25,654,798,1198,1310 'criteria':1163,1410 'data':240,295,300,407,924 'databas':282 'debug':3,18,57,1055,1268,1334 'deep':412 'defense-in-depth.md':1285 'depend':259,530,1222 'describ':1378 'develop':683,1308 'diagnost':287 'didn':125,608 'diff':255 'differ':263,508,511,518,788,910,940,1185 'directori':420,1273 'discuss':769,827 'document':1232 'doesn':729 'driven':682,1307 'echo':341,346,356,365,374 'elsewher':801 'emerg':107,1049 'encount':6 'enter':296 'env':357,362 'environ':369,540,1390 'environment':262,1219 'environment-specif':1389 'environment/config':304 'error':190,197,215,410,1168,1242 'especi':102 'everi':233,498,517 'evid':266,315,322,991,1173 'exact':204,228 'exampl':332,466,1182 'excus':1028 'exit':301 'expert':1395 'extern':1224 'fail':325,400,655,688,774,840,954,1311 'failur':10,45,88,97,1146,1148 'fast':1045 'faster':163,1057 'file':213 'find':36,383,445,458,464,1180,1282,1292 'find-ident':382 'first':67,1067,1070,1095,1352 'first-tim':1351 'fix':16,21,41,43,62,78,114,122,124,159,187,285,448,462,593,618,646,676,693,715,728,736,765,773,782,790,797,825,835,859,891,917,928,935,953,998,1071,1087,1090,1099,1133,1142,1155,1200,1324,1342,1344,1354 'flag':848 'flow':408,925 'follow':851 'form':554,611,1188 'four':167 'framework':672 'frustrat':1011 'fulli':131,503,896 'fundament':805,809,1004 'futur':1248 'gather':238,265,314,992,1172 'git':254 'grep':363 'guarante':154,1122 'guess':109,243,994,1060 'guess-and-check':1059 'handl':1239 'happen':232,978 'haven':70 'help':640 'hour':1348 'howev':519 'human':830,962 'hurri':152 'hypothesi':548,556,585,613,841,1187,1195 'ident':347,348,350,364,366,384,392 'identifi':324,507,698,1184 'impact':1332 'implement':488,492,645,691,795,1197,1237 'improv':709 'incomplet':1258 'indic':778 'inertia':818 'inform':751 'input':1404 'instrument':288 'integr':98 'introduc':1361 'investig':66,183,328,862,919,1069,1214,1235,1249,1259 'iron':59 'isn':1014 'isol':1106 'issu':32,86,99,134,139,723,1030,1038,1216 'keep':440 'key':1160 'keychain':375,380 'know':626,637 'later':863 'law':60 'layer':310,335,338,352,370,386,399,1290 'let':889,1131 'letter':48 'limit':1366 'line':211,499 'list':379,516,916 'list-keychain':378 'll':882,907,1082,1116 'locat':467 'log':293,298 'long':1114 'm':707 'main':914 'make':108,545,578 'manag':156 'mani':735 'manual':883 'mask':30 'massiv':792 'match':1375 'matter':527 'mean':945 'messag':191,1243 'method':552 'might':900 'minim':577,1191 'minut':1340 'miss':1412 'monitoring/logging':1246 'multi':269,334 'multi-compon':268 'multi-lay':333 'multipl':121,275,594,874,1098,1289 'must':170,673 'near':1362 'need':536,1035 'new':26,258,612,750,784,799,937,1110,1194,1359 'next':178 'note':210 'number':212 'obvious':116 'often':201 'one':112,586,666,699,926,1140 'one-off':665 'origin':433,1283 'output':1384 'overview':19 'part':1265 'partial':1120 'partner':831,963 'pass':717,1205 'past':196 'patch':29 'path':214 'pattern':456,460,489,502,777,808,902,1074,1119,1152,1179 'perform':94 'permiss':1405 'phase':73,168,173,179,454,546,606,643,744,949,959,1024,1159,1314 'place':789,941 'poll':1301 'possibl':581,659,664 'pressur':106 'pretend':635 'previous':123 'principl':34 'probabl':887 'problem':95,780,915,938,1130,1150 'proceed':175 'process':51,852,1036,1043,1053,1207,1230 'product':91 'propag':305 'proper':687 'propos':15,77,284,920,997 'prove':1096 'question':756,775,804,955,1003,1151 'quick':28,113,427,858,1157 'random':20,1343 'rate':1355 'ration':1027 're':149,747,967,996,1009 're-analyz':746 'read':189,206,490,497,1124,1167 'real':1330 'real-world':1329 'realiti':1029 'recent':246,256 'red':847 'redirect':974 'refactor':712,793,821 'refer':486,491,1112,1158 'relat':1302 'reliabl':224 'replac':1296 'reproduc':218,237,1169 'reproduct':660 'requir':791,1403 'research':641 'resolv':725,1203 'retri':1240 'return':742,947,1022 'reveal':397,783,936,1208,1215 'review':1396 'rework':155 'right':1077 'root':37,64,145,181,564,648,696,1040,1138,1165,1210,1254,1293 'root-cause-tracing.md':417,1274 'run':311,876 'rush':153 'safeti':1406 'save':1102 'say':627,903 'scientif':551 'scope':1377 'script':355,361,373,669 'secret':342,401 'secur':377,381 'see':416,869,958,1019,1128,1135 'seem':115,140 'servic':281 'session':1335 'set':349,538,1072 'share':785 'sheer':817 'show':316,985 'sign':279,372,389,391 'signal':965 'similar':468,478 'simpl':141,142,1032,1037,1047 'simplest':658 'singl':555,692 'skill':684,1303,1369 'skill-systematic-debugging' 'skim':496 'skip':137,195,878 'small':520 'smallest':580 'solut':205,921 'sound':810 'sourc':447,450 'source-sickn33' 'specif':330,572,1391 'spirit':55 'stack':207,415,1280 'start':1080 'state':307,376,557 'state/coupling/problem':786 'step':229,759,1316 'stick':813,1093 'stop':732,754,802,849,946,993,1021,1397 'stuck':1010 'substitut':1387 'success':1162,1328,1409 'superpow':679,1304,1318 'support':1260 'symptom':42,453,652,800,826,1007,1136 'system':271,273,336 'systemat':2,17,161,1054,1213,1267,1336 'systematic-debug':1 'task':1373 'technic':85 'techniqu':426,1261,1263 'tempt':110 'test':9,87,550,576,584,656,662,668,681,689,716,721,877,880,1084,1094,1190,1199,1204,1306,1312,1393 'test-driven-develop':680,1305 'theori':1189 'thing':595 'think':560,857 'thrash':165,1063,1350 'time':23,105,234,590,703,1051,1103,1221,1353 'timeout':1241,1298 'timing-depend':1220 'top':620 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'trace':208,406,425,441,923,1275 'treat':1382 'tri':120,739,865,932,1065 'trigger':222,1284 'truli':1218 'ultrathink':1001 'under':31 'understand':132,500,529,631,897,1000,1121,1137,1174 'unexpect':12,92 'unset':351 'untest':1089 'us':986 'use':4,81,82,100,677,1367 'v':385 'vagu':574 'valid':1287,1392 'valu':432,439 'var':358 'variabl':587 've':118,1227 'verbos':393 'verif':1320 'verifi':303,599,714,884,982,1201,1323 'verification-before-complet':1319 'version':428 'violat':46,53 'vs':823,1357,1364 'want':157 'warn':199 'wast':22 'watch':971 'without':63,767,918,981,999 'work':127,465,469,475,513,604,610,731,872,901,1016,1088,1108,1181,1325 'workflow':340,345,402,403 'world':1331 'write':568,686,1083 'wrong':845,970 'x':561,632,867,888,904 'y':567 'yes':605 'zero':1363","prices":[{"id":"ba430e2d-8262-4e18-8e81-0def6ce646fd","listingId":"2ed9cff8-50f9-4576-89bb-93a3d9a47270","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:45:46.953Z"}],"sources":[{"listingId":"2ed9cff8-50f9-4576-89bb-93a3d9a47270","source":"github","sourceId":"sickn33/antigravity-awesome-skills/systematic-debugging","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/systematic-debugging","isPrimary":false,"firstSeenAt":"2026-04-18T21:45:46.953Z","lastSeenAt":"2026-04-22T06:51:57.972Z"}],"details":{"listingId":"2ed9cff8-50f9-4576-89bb-93a3d9a47270","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"systematic-debugging","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34460,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-22T06:40:00Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"9af232e8f2ac9ea0b4757e17a01daac535b508fb","skill_md_path":"skills/systematic-debugging/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/systematic-debugging"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"systematic-debugging","description":"Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes"},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/systematic-debugging"},"updatedAt":"2026-04-22T06:51:57.972Z"}}