{"id":"ea1be2a0-3deb-42d5-bcdb-ef4a7ff149e9","shortId":"xStVba","kind":"skill","title":"diagnose","tagline":"Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance r","description":"# Diagnose\n\nA discipline for hard bugs. Skip phases only when explicitly justified.\n\nWhen exploring the codebase, build a clear mental model of the relevant modules and check any ADRs or design notes in the area you're touching.\n\n## Phase 1 — Build a feedback loop\n\n**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.\n\nSpend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**\n\n### Ways to construct one — try them in roughly this order\n\n1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.\n2. **Curl / HTTP script** against a running dev server.\n3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.\n4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.\n5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.\n6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.\n7. **Property / fuzz loop.** If the bug is \"sometimes wrong output\", run 1000 random inputs and look for the failure mode.\n8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate \"boot at state X, check, repeat\" so you can `git bisect run` it.\n9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.\n10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.\n\nBuild the right feedback loop, and the bug is 90% fixed.\n\n### Iterate on the loop itself\n\nTreat the loop as a product. Once you have _a_ loop, ask:\n\n- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)\n- Can I make the signal sharper? (Assert on the specific symptom, not \"didn't crash\".)\n- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)\n\nA 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.\n\n### Non-deterministic bugs\n\nThe goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.\n\n### When you genuinely cannot build a loop\n\nStop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.\n\nDo not proceed to Phase 2 until you have a loop you believe in.\n\n## Phase 2 — Reproduce\n\nRun the loop. Watch the bug appear.\n\nConfirm:\n\n- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.\n- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).\n- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.\n\nDo not proceed until you reproduce the bug.\n\n## Phase 3 — Hypothesise\n\nGenerate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.\n\nEach hypothesis must be **falsifiable**: state the prediction it makes.\n\n> Format: \"If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse.\"\n\nIf you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.\n\n**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly (\"we just deployed a change to #3\"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.\n\n## Phase 4 — Instrument\n\nEach probe must map to a specific prediction from Phase 3. **Change one variable at a time.**\n\nTool preference:\n\n1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.\n2. **Targeted logs** at the boundaries that distinguish hypotheses.\n3. Never \"log everything and grep\".\n\n**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.\n\n**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.\n\n## Phase 5 — Fix + regression test\n\nWrite the regression test **before the fix** — but only if there is a **correct seam** for it.\n\nA correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.\n\n**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.\n\nIf a correct seam exists:\n\n1. Turn the minimised repro into a failing test at that seam.\n2. Watch it fail.\n3. Apply the fix.\n4. Watch it pass.\n5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.\n\n## Phase 6 — Cleanup + post-mortem\n\nRequired before declaring done:\n\n- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)\n- [ ] Regression test passes (or absence of seam is documented)\n- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)\n- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)\n- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns\n\n**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/architecture-audit` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.","tags":["diagnose","agent","skills","helderberto","agent-skills","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli","markdown"],"capabilities":["skill","source-helderberto","skill-diagnose","topic-agent-skills","topic-ai-tools","topic-antigravity","topic-claude-code","topic-cursor","topic-developer-tools","topic-gemini-cli","topic-markdown","topic-plugin","topic-sdlc","topic-skills","topic-tracer-bullet"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/helderberto/agent-skills/diagnose","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add helderberto/agent-skills","source_repo":"https://github.com/helderberto/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (6,760 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:09:13.026Z","embedding":null,"createdAt":"2026-05-18T13:14:53.064Z","updatedAt":"2026-05-18T19:09:13.026Z","lastSeenAt":"2026-05-18T19:09:13.026Z","tsv":"'/architecture-audit':1110 '1':78,158,477,782,976,1006,1036 '10':325 '100':462 '1000':267 '2':170,435,550,560,796,988 '3':179,645,648,732,773,805,992 '30':424 '4':194,761,996 '5':206,649,864,1000 '50':472 '6':229,1017 '7':255 '8':276 '9':304 '90':361 'a4f2':822 'absenc':1042 'access':509 'across':596 'actual':633 'add':464,533 'address':634 'adr':67 'afk':759 'agent':98 'agent-runn':97 'aggress':141 'alreadi':738 'amount':128 'anchor':661 'answer':1094 'appear':282,568 'appli':993 'architectur':956,1096 'area':73 'artifact':518 'ask':379,504,1085 'assert':203,400 'autom':290 'avail':908 'b':515 'back':349 'bare':429 'baselin':849 'bash':327 'beat':793 'becom':827 'believ':557 'better':430 'big':743 'bisect':110,277,301,858 'block':748 'boot':291 'boundari':801 'branch':838 'breakpoint':792 'broken/throwing/failing':33 'browser':196 'bug':7,29,44,104,166,247,261,281,359,446,474,567,589,604,643,686,896,919,934,960,1091 'build':55,79,352,492 'c':530 'cach':385 'call':254,903 'caller':915,922,1103 'cannot':491,694 'captur':209,346,517,616 'caus':109,681 'chain':930 'chang':730,774,1097 'cheap':741 'check':65,295 'checkpoint':742 'clean':452 'cleanup':823,1018 'clear':57,1062 'clearly-mark':1061 'cli':180 'click':335 'code':132,225,248 'codebas':54,955 'commit':287,1076 'confid':941 'config':321 'confirm':569 'construct':150 'consum':118 'core':523 'correct':881,886,944,973,1071 'coupl':1105 'crash':408 'creativ':143 'curl':171 'dataset':288 'debug':25,441,612,813,821,1048,1064 'debug-a4f2':820 'debugg':476,487,783,1082 'declar':1024 'delet':1056 'dep':243 'deploy':728 'describ':35,578 'design':69 'determinist':96,414,437,445,603 'dev':177 'diagnos':1,23,39 'diagnosi':3 'didn':406 'die':836 'dif':186 'diff':323 'differ':581 'differenti':305 'disappear':687 'discard':703 'disciplin':2,41 'disk':220 'disproportion':137 'distinguish':803 'document':1046 'dom/console/network':205 'domain':719 'done':1025 'drive':200,336 'dump':522,524 'e.g':819 'e2e':169 'effort':138 'els':88 'end':826 'enough':609 'env':788 'environ':512 'error':620 'establish':847 'event':217 'everi':812 'everyth':87,808 'exact':618 'exercis':245,893 'exist':946,975 'explicit':49,499 'explor':52 'fail':159,983,991 'failur':274,574,582,593 'fals':940 'falsifi':671 'fast':95 'faster':384 'feed':348 'feedback':81,355,1007 'file':520 'filesystem':420 'find':107,951 'first':664,860 'fix':15,362,591,632,861,865,874,995,1120 'fixtur':184 'flag':965 'flake':473 'flaki':426 'format':677 'freez':421 'function':253 'fuzz':257 'generat':647,660 'genuin':490 'git':300 'give':146,939 'goal':448 'good':192,1099 'grep':810,830,1051 'hand':1106 'happen':584 'har':231,278,519,852 'hard':6,43 'headless':195 'hidden':1104 'high':608 'higher':456 'hitl':326 'http':172 'human':333 'hypothes':651,735,804 'hypothesi':112,659,668,699,1067 'hypothesis':13,541,646 'hypothesis-test':111 'idea':666 'inform':1128 'init':389 'inject':469 'input':185,269,310 'inspect':785 'instant':725 'instead':846 'instrument':14,115,536,762,1049 'integr':168 'invoc':181 'involv':1095 'isol':228,419 'iter':363 'justifi':50 'keep':480 'know':734 'knowledg':720 'known':191,285 'known-good':190 'last':329 'later':627 'learn':1083 'list':500,710 'locat':1065 'lock':963 'log':218,521,795,798,807,814,832,835,842 'longer':1029 'look':271 'loop':4,82,258,306,342,356,366,370,378,427,433,438,459,494,544,555,564,571,1008,1037 'make':382,396,411,676,684,689,1115 'map':766 'mark':1063 'measur':850,859 'mechan':90 'mental':58 'messag':621,1078 'minim':235 'minimis':12,979,1014 'mock':242 'mode':275,575 'model':59 'modul':63 'mortem':1021 'move':1058 'multipl':597,921 'must':334,669,765 'narrow':390,466 'nearbi':587 'need':920 'network':214,422 'never':806 'new':317 'new-vers':316 'next':969,1081 'non':444,602 'non-determinist':443,601 'note':70,952 'occur':900 'often':717 'old':313 'old-vers':312 'one':126,151,240,775,791,889 'order':157 'origin':1011,1026 'output':265,324,347,623 'parallelis':463 'pass':999,1040 'pass/fail':100 'path':226,249 'pattern':897 'payload':216 'perf':837 'perform':9,37,840 'performance.now':853 'permiss':531 'phase':46,77,549,559,628,644,760,772,863,970,1005,1016,1035 'pin':415 'plan':856 'plausibl':665 'playwright':198 'post':1020 'post-mortem':1019 'pr':1077 'predict':674,697,770 'prefer':781 'prefix':818,1053 'prevent':958,1089 'probe':764 'proceed':539,547,638,751 'produc':572 'product':373,535 'profil':854 'properti':256 'prototyp':1055 'puppet':199 'queri':855 'r':38 'rais':481 'random':268 'rank':650,709,724,754 'rate':458,483,610 're':75,723,1002,1032 're-rank':722 're-run':1001,1031 'reach':164 'real':213,895 'recommend':1117 'record':526 'refus':144 'regress':10,17,841,866,870,936,1038 'regression-test':16 'relev':62 'remov':1050 'repeat':296 'repl':784 'replay':207,221 'replic':928 'report':27 'repro':453,980,1027 'reproduc':11,513,561,595,605,641,1030 'reproduct':457 'request':215 'requir':1022 'resort':330 'right':354 'rng':418 'rough':155 'rule':739 'run':176,266,302,307,562,598,1003,1033 'runnabl':99 'save':134,211 'saver':745 'say':22,30,497 'scenario':1015 'scope':393 'screen':525 'script':173,197,328 'scripts/hitl-loop.template.sh':339 'seam':163,882,887,909,945,974,987,1044,1101 'second':425,436,862 'seed':417 'server':178 'servic':241 'setup':386 'shallow':912 'sharpen':705 'sharper':399 'show':707 'signal':101,120,398 'singl':252,658,829,914 'single-cal':913 'single-hypothesi':657 'site':904 'skill':86,1111 'skill-diagnose' 'skip':45,387 'sleep':470 'slow':624 'snapshot':193 'someth':31 'sometim':263 'source-helderberto' 'specif':403,769,1114 'spend':136 'spin':232 'stare':130 'start':1133 'state':286,293,672,695,1073 'stdout':187 'still':344 'stop':495 'stress':465 'structur':345 'subset':236 'superpow':442 'support':789 'surviv':833 'symptom':404,619 'system':239 'tag':811,834 'tangl':1102 'target':797 'temporari':534 'ten':794 'test':18,113,160,392,653,715,867,871,892,916,924,937,984,1039,1100 'throwaway':230,1054 'time':416,467,625,744,779,851 'timestamp':528 'tool':780 'topic-agent-skills' 'topic-ai-tools' 'topic-antigravity' 'topic-claude-code' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'topic-markdown' 'topic-plugin' 'topic-sdlc' 'topic-skills' 'topic-tracer-bullet' 'touch':76 'trace':210 'treat':368 'tri':152,503 'trigger':461,932 'turn':977,1069 'two':284,320 'ui':202 'un':1013 'un-minimis':1012 'uniqu':817 'unit':167,923 'unrel':388 'untag':831 'use':19 'user':21,506,577,713,757 'usual':844 'variabl':776 've':737 'verifi':630 'version':289,314,318 'vibe':702 'vs':315 'watch':565,989,997 'way':148 'whatev':162,511 'window':468 'without':542 'wors':691 'would':1087 'write':868 'wrong':264,588,590,622,845 'x':294","prices":[{"id":"238d2033-261d-494a-9cee-398125741387","listingId":"ea1be2a0-3deb-42d5-bcdb-ef4a7ff149e9","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"helderberto","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:53.064Z"}],"sources":[{"listingId":"ea1be2a0-3deb-42d5-bcdb-ef4a7ff149e9","source":"github","sourceId":"helderberto/agent-skills/diagnose","sourceUrl":"https://github.com/helderberto/agent-skills/tree/main/skills/diagnose","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:53.064Z","lastSeenAt":"2026-05-18T19:09:13.026Z"}],"details":{"listingId":"ea1be2a0-3deb-42d5-bcdb-ef4a7ff149e9","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"helderberto","slug":"diagnose","github":{"repo":"helderberto/agent-skills","stars":8,"topics":["agent-skills","ai","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli","markdown","plugin","sdlc","skills","tracer-bullet"],"license":"mit","html_url":"https://github.com/helderberto/agent-skills","pushed_at":"2026-05-14T11:37:47Z","description":"My personal SDLC toolbelt for AI coding agents — PRD to ship.","skill_md_sha":"862434746e030fe0e0d548a1ec56f1014c1849d7","skill_md_path":"skills/diagnose/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/helderberto/agent-skills/tree/main/skills/diagnose"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"diagnose","description":"Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression."},"skills_sh_url":"https://skills.sh/helderberto/agent-skills/diagnose"},"updatedAt":"2026-05-18T19:09:13.026Z"}}