[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6KWT94AJY2MVD3QA68G71GR":3,"skill-same:01M6KWT94AJY2MVD3QA68G71GR":73},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":50,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M6KWT94AJY2MVD3QA68G71GR","diagnosing-bugs",null,"A disciplined diagnosis loop for hard bugs and performance regressions: build a tight feedback loop that goes red on this bug, minimise, hypothesise, instrument, fix at the root cause with a regression test, and clean up. Use when the user says \"debug\" or \"diagnose\", or reports something broken, throwing, failing, flaky, or slow.","dougborg\u002Fharness-kit","dougborg","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1261222?v=4","01M6KWS4PB51EYD4ZDJJSGNGB2","Doug Borg","01M6KWS4T8ZZW6SX5QZS9B5BN2",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fclaude-skills\u002Fdiagnosing-bugs\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"diagnosing bugs","bugs","regression test","performance","for","with","diagnosis","build","clean","reports","up","test","use","fix","broken","feedback","regression","loop","diagnose","debug","2026-11-10 10:12:30",false,"---\nname: diagnosing-bugs\ndescription: >-\n  A disciplined diagnosis loop for hard bugs and performance regressions:\n  build a tight feedback loop that goes red on this bug, minimise, hypothesise,\n  instrument, fix at the root cause with a regression test, and clean up. Use\n  when the user says \"debug\" or \"diagnose\", or reports something broken,\n  throwing, failing, flaky, or slow.\n---\n\n# Diagnosing Bugs\n\nA discipline for hard bugs. Skip a phase only when you can say why.\n\nRead the project's `GLOSSARY.md` (if any) for a clear model of the modules\ninvolved, and check ADRs in the area.\n\n**Redact as you go.** This loop shows commands, output, and captured artifacts.\nWrite `\u003CREDACTED>` in place of every secret, keep credentials in environment\nvariables the loop reads, and quote only the lines of a captured artifact that\ncarry the signal. If redacted output isn't enough to diagnose, say so and ask.\n\n## Phase 1: Build a feedback loop\n\nThis is the skill. With a **tight** pass\u002Ffail signal that goes **red** on this\nbug, bisection, hypotheses, and instrumentation all just consume it. Without\none, no amount of reading code will find the cause. Spend disproportionate\neffort here, and keep at it.\n\nWays to build one, roughly in this order:\n\n1. A failing test at whatever seam reaches the bug: unit, integration, or\n   end-to-end.\n2. A curl or HTTP script against a running dev server.\n3. A CLI run with a fixture input, diffing output against a known-good\n   snapshot.\n4. A headless browser script (Playwright, Puppeteer) asserting on the DOM,\n   console, or network.\n5. Replaying a captured trace: save a real request, payload, or event log and\n   run it through the code path in isolation.\n6. A throwaway harness: the smallest subset of the system (one service, stub\n   dependencies) that reaches the bug's path in one call.\n7. A property or fuzz loop for \"sometimes wrong\": many random inputs, looking\n   for the failure mode.\n8. A bisection harness when the bug appeared between two known states\n   (commits, datasets, versions), so `git bisect run` can drive it.\n9. A differential loop: the same input through the old and new version (or two\n   configs), diffing the output.\n10. A human-in-the-loop script, as a last resort when a person must click.\n    Copy `${CLAUDE_SKILL_DIR}\u002Fhitl-loop.template.sh` into the repo's scratch space and\n    edit its steps. The person runs it in their own terminal, since your shell\n    has no terminal for them to type into: in Claude Code they type\n    `! bash \u003Cpath>` at the prompt, elsewhere they run it and paste the output\n    back. Done when the `--- Captured ---` block is back in the conversation.\n\n**Tighten it.** Make it faster (cache setup, narrow the scope), sharper (assert\nthe exact symptom, not \"didn't crash\"), and more deterministic (pin time, seed\nrandomness, isolate the filesystem and network). For a flaky bug, aim for a\nhigher reproduction rate rather than a clean repro: loop the trigger,\nparallelise, add stress, narrow timing windows. A 50% flake is debuggable; 1% is not yet.\n\n**If you cannot build one,** stop and say so, list what you tried, and ask for\naccess to an environment that reproduces it, a redacted captured artifact (HAR\nfile, log dump, core dump, timestamped recording), or permission to add\ntemporary production instrumentation.\n\nDone when you can name **one command**, already run at least once (show it and\nits redacted output), that is:\n\n- **Red-capable:** it drives the real bug path and asserts the user's exact\n  symptom, so it goes red on this bug and green once it is fixed.\n- **Deterministic:** the same verdict every run, or for a flaky bug a pinned,\n  high reproduction rate.\n- **Fast:** seconds, not minutes.\n- **Agent-runnable:** you can run it unattended, or, for the human-in-the-loop\n  case, the person can run the script and hand back its output.\n\nReading code to build a theory before this command exists is the exact failure\nthis skill prevents. No red-capable command, no Phase 2.\n\n## Phase 2: Reproduce and minimise\n\nRun the loop and watch it go red. Confirm the failure is the one the user\ndescribed, not a nearby different one; that it reproduces across runs (or at a\ndebuggable rate); and capture the exact symptom so later phases can check the\nfix against it.\n\nThen cut inputs, callers, config, data, and steps one at a time, re-running\nafter each cut, keeping only what the failure needs. A minimal repro shrinks\nthe hypothesis space and becomes the regression test. Done when every\nremaining element is load-bearing: removing any one turns the loop green.\n\n## Phase 3: Hypothesise\n\nWrite 3-5 ranked hypotheses before testing any; a single hypothesis anchors on\nthe first plausible idea. Each must be falsifiable: \"If X is the cause, then\nchanging Y makes the bug disappear and changing Z makes it worse.\" A\nhypothesis with no prediction is a hunch: sharpen it or drop it.\n\nShow the ranked list to the user before testing. They often know something\nthat re-ranks it at once (\"we changed #3 yesterday\"), or what's already been\nruled out. Proceed on your own ranking if they're away. Done when the ranked,\nfalsifiable list has been shown.\n\n## Phase 4: Instrument\n\nEach probe tests one prediction from Phase 3; change one variable at a time.\nPrefer a debugger or REPL over logs, and targeted logs at the boundaries that\nseparate hypotheses over logging everything. Tag every debug line with one\nunique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep.\n\nFor performance regressions, measure before fixing: establish a baseline\n(timing harness, profiler, query plan), then bisect.\n\nDone when one hypothesis is confirmed by a probe and each of the others is\nruled out by one, or the evidence sends you back to Phase 3 with new\nhypotheses.\n\nWatch for a spiral: after three rounds of \"still broken\", stop changing code.\nName the assumption most likely to be wrong (the bug is where you think, the\nloop tests what you think, the build is the one you changed), and ask the user\none diagnostic question before the next change.\n\n## Phase 5: Fix at the root, with a regression test\n\nA report names a symptom. Before editing, list every caller of the function\nyou're about to change and note which of them hit the same defect. Then fix\nthe defect where all those callers route through, at its cause, not where the\nsymptom shows: patching only the path the report names leaves the sibling\ncallers broken, and a guard that hides a wrong value is still a symptom\npatch.\n\nWrite the regression test before the fix, at a **correct seam**: one where the\ntest reproduces the bug as it happens at the call site. If the only seam\navailable is too shallow (one caller when the bug needs several, a unit test\nthat can't reproduce the chain), a test there gives false confidence; note\nthat the architecture prevents locking the bug down, and say so in the\nreport. With a correct seam:\n\n1. Turn the minimised repro into a failing test there, and watch it fail.\n2. Apply the fix, and watch it pass.\n3. Re-run the Phase 1 loop against the original, un-minimised scenario.\n\nDone when the callers are listed, the regression test went red then green\n(or the missing seam is noted), and the Phase 1 loop is green.\n\n## Phase 6: Clean up\n\nDone when:\n\n- [ ] The Phase 1 loop no longer reproduces the bug\n- [ ] The regression test passes, or the missing seam is documented\n- [ ] No `[DEBUG-...]` lines remain (grep the prefix)\n- [ ] Throwaway harnesses are deleted or moved somewhere clearly marked\n- [ ] The commit or PR message states the hypothesis that proved correct, so\n      the next person learns from it\n","# Diagnosing Bugs\n\nA discipline for hard bugs. Skip a phase only when you can say why.\n\nRead the project's `GLOSSARY.md` (if any) for a clear model of the modules\ninvolved, and check ADRs in the area.\n\n**Redact as you go.** This loop shows commands, output, and captured artifacts.\nWrite `\u003CREDACTED>` in place of every secret, keep credentials in environment\nvariables the loop reads, and quote only the lines of a captured artifact that\ncarry the signal. If redacted output isn't enough to diagnose, say so and ask.\n\n## Phase 1: Build a feedback loop\n\nThis is the skill. With a **tight** pass\u002Ffail signal that goes **red** on this\nbug, bisection, hypotheses, and instrumentation all just consume it. Without\none, no amount of reading code will find the cause. Spend disproportionate\neffort here, and keep at it.\n\nWays to build one, roughly in this order:\n\n1. A failing test at whatever seam reaches the bug: unit, integration, or\n   end-to-end.\n2. A curl or HTTP script against a running dev server.\n3. A CLI run with a fixture input, diffing output against a known-good\n   snapshot.\n4. A headless browser script (Playwright, Puppeteer) asserting on the DOM,\n   console, or network.\n5. Replaying a captured trace: save a real request, payload, or event log and\n   run it through the code path in isolation.\n6. A throwaway harness: the smallest subset of the system (one service, stub\n   dependencies) that reaches the bug's path in one call.\n7. A property or fuzz loop for \"sometimes wrong\": many random inputs, looking\n   for the failure mode.\n8. A bisection harness when the bug appeared between two known states\n   (commits, datasets, versions), so `git bisect run` can drive it.\n9. A differential loop: the same input through the old and new version (or two\n   configs), diffing the output.\n10. A human-in-the-loop script, as a last resort when a person must click.\n    Copy `${CLAUDE_SKILL_DIR}\u002Fhitl-loop.template.sh` into the repo's scratch space and\n    edit its steps. The person runs it in their own terminal, since your shell\n    has no terminal for them to type into: in Claude Code they type\n    `! bash \u003Cpath>` at the prompt, elsewhere they run it and paste the output\n    back. Done when the `--- Captured ---` block is back in the conversation.\n\n**Tighten it.** Make it faster (cache setup, narrow the scope), sharper (assert\nthe exact symptom, not \"didn't crash\"), and more deterministic (pin time, seed\nrandomness, isolate the filesystem and network). For a flaky bug, aim for a\nhigher reproduction rate rather than a clean repro: loop the trigger,\nparallelise, add stress, narrow timing windows. A 50% flake is debuggable; 1% is not yet.\n\n**If you cannot build one,** stop and say so, list what you tried, and ask for\naccess to an environment that reproduces it, a redacted captured artifact (HAR\nfile, log dump, core dump, timestamped recording), or permission to add\ntemporary production instrumentation.\n\nDone when you can name **one command**, already run at least once (show it and\nits redacted output), that is:\n\n- **Red-capable:** it drives the real bug path and asserts the user's exact\n  symptom, so it goes red on this bug and green once it is fixed.\n- **Deterministic:** the same verdict every run, or for a flaky bug a pinned,\n  high reproduction rate.\n- **Fast:** seconds, not minutes.\n- **Agent-runnable:** you can run it unattended, or, for the human-in-the-loop\n  case, the person can run the script and hand back its output.\n\nReading code to build a theory before this command exists is the exact failure\nthis skill prevents. No red-capable command, no Phase 2.\n\n## Phase 2: Reproduce and minimise\n\nRun the loop and watch it go red. Confirm the failure is the one the user\ndescribed, not a nearby different one; that it reproduces across runs (or at a\ndebuggable rate); and capture the exact symptom so later phases can check the\nfix against it.\n\nThen cut inputs, callers, config, data, and steps one at a time, re-running\nafter each cut, keeping only what the failure needs. A minimal repro shrinks\nthe hypothesis space and becomes the regression test. Done when every\nremaining element is load-bearing: removing any one turns the loop green.\n\n## Phase 3: Hypothesise\n\nWrite 3-5 ranked hypotheses before testing any; a single hypothesis anchors on\nthe first plausible idea. Each must be falsifiable: \"If X is the cause, then\nchanging Y makes the bug disappear and changing Z makes it worse.\" A\nhypothesis with no prediction is a hunch: sharpen it or drop it.\n\nShow the ranked list to the user before testing. They often know something\nthat re-ranks it at once (\"we changed #3 yesterday\"), or what's already been\nruled out. Proceed on your own ranking if they're away. Done when the ranked,\nfalsifiable list has been shown.\n\n## Phase 4: Instrument\n\nEach probe tests one prediction from Phase 3; change one variable at a time.\nPrefer a debugger or REPL over logs, and targeted logs at the boundaries that\nseparate hypotheses over logging everything. Tag every debug line with one\nunique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep.\n\nFor performance regressions, measure before fixing: establish a baseline\n(timing harness, profiler, query plan), then bisect.\n\nDone when one hypothesis is confirmed by a probe and each of the others is\nruled out by one, or the evidence sends you back to Phase 3 with new\nhypotheses.\n\nWatch for a spiral: after three rounds of \"still broken\", stop changing code.\nName the assumption most likely to be wrong (the bug is where you think, the\nloop tests what you think, the build is the one you changed), and ask the user\none diagnostic question before the next change.\n\n## Phase 5: Fix at the root, with a regression test\n\nA report names a symptom. Before editing, list every caller of the function\nyou're about to change and note which of them hit the same defect. Then fix\nthe defect where all those callers route through, at its cause, not where the\nsymptom shows: patching only the path the report names leaves the sibling\ncallers broken, and a guard that hides a wrong value is still a symptom\npatch.\n\nWrite the regression test before the fix, at a **correct seam**: one where the\ntest reproduces the bug as it happens at the call site. If the only seam\navailable is too shallow (one caller when the bug needs several, a unit test\nthat can't reproduce the chain), a test there gives false confidence; note\nthat the architecture prevents locking the bug down, and say so in the\nreport. With a correct seam:\n\n1. Turn the minimised repro into a failing test there, and watch it fail.\n2. Apply the fix, and watch it pass.\n3. Re-run the Phase 1 loop against the original, un-minimised scenario.\n\nDone when the callers are listed, the regression test went red then green\n(or the missing seam is noted), and the Phase 1 loop is green.\n\n## Phase 6: Clean up\n\nDone when:\n\n- [ ] The Phase 1 loop no longer reproduces the bug\n- [ ] The regression test passes, or the missing seam is documented\n- [ ] No `[DEBUG-...]` lines remain (grep the prefix)\n- [ ] Throwaway harnesses are deleted or moved somewhere clearly marked\n- [ ] The commit or PR message states the hypothesis that proved correct, so\n      the next person learns from it\n",{"name":5,"description":7},"main","023b01bfb4a86fbf1e38a749f1044cce3e5da67d","claude-skills\u002Fdiagnosing-bugs",1,"https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit","https:\u002F\u002Fgithub.com\u002Fdougborg","http:\u002F\u002Fdougborg.org","Platforms and Infrastructure Software Engineer","2026-11-13 07:43:37",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add dougborg\u002Fharness-kit --skill diagnosing-bugs",{"tool":59,"command":60},"bunx","bunx skills add dougborg\u002Fharness-kit --skill diagnosing-bugs",{"tool":62,"command":63},"pnpm","pnpm dlx skills add dougborg\u002Fharness-kit --skill diagnosing-bugs","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fclaude-skills\u002Fdiagnosing-bugs\u002FSKILL.md",true,[67],{"path":68,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":71,"sourceHtmlUrl":72},"hitl-loop.template.sh","SCRIPT","脚本",1348,"https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fclaude-skills\u002Fdiagnosing-bugs\u002Fhitl-loop.template.sh",[74,92,113,144,168,185],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":85,"publishedAt":39},"01M6KX4J65S5FZKMSN5DQNPSZM","teach","Teach yourself a topic over several sessions, with lessons, references, and a record of what you've learned.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fteach\u002FSKILL.md",[80],{"categoryNo":81,"categoryName":82,"taxonomyType":83,"taxonomyTypeDesc":84},"01JBSEEDCAT000000000000039","教师与教育","PROFESSION","适用职业",[76,86,87,24,88,89,90,91],"lessons","you","learned","record","references","sessions",{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":103,"publishedAt":39},"01M6KX4FSSG7MHF00JDT5QT0BQ","svg-logo-designer","Generate SVG logos with multiple concepts, layouts, and color variations.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fsvg-logo-designer\u002FSKILL.md",[98],{"categoryNo":99,"categoryName":100,"taxonomyType":101,"taxonomyTypeDesc":102},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",[104,105,106,107,108,109,24,110,111,112],"logo","designer","svg logo designer","SVG","color","concepts","write","read","generate",{"skillNo":114,"name":115,"nameZh":6,"description":116,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":125,"publishedAt":39},"01M6KX4BD3J9MZPPSH4MENH7FP","documentation-writer","Writes and revises human-facing documentation — READMEs, contributor and setup guides, reference pages, architecture notes, CLAUDE.md, and changelog entries. Covers picking the right document type for the question being asked, structuring for skimming, writing examples that actually run, and keeping docs from going stale. Use when creating or rewriting docs, when a README has drifted from the code, or when deciding where a piece of information belongs. For SKILL.md and agent files, use \u002Fskill-writer instead.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fdocumentation-writer\u002FSKILL.md",[119,122],{"categoryNo":120,"categoryName":121,"taxonomyType":101,"taxonomyTypeDesc":102},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":123,"categoryName":124,"taxonomyType":83,"taxonomyTypeDesc":84},"01JBSEEDCAT000000000000036","内容创作者",[126,127,128,129,130,131,132,133,31,134,135,136,137,138,139,23,140,141,142,143],"writer","documentation writer","documentation","entries","changelog","architecture","document","files","question","README","notes","code","examples","pages","information","guides","type","writing",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":150,"publishedAt":39},"01M6KX47ZJ4ZWHDN3MY8SYAWZZ","adhd-mode","Shapes every response for a reader with ADHD: the next action first, numbered steps, progress restated each turn, tangents held back, concrete time estimates, wins made visible. Stays on for the rest of the session until the reader says \"stop adhd mode\". On Claude Code, the harness-kit:adhd output style does the same without invoking this skill.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting\u002Fadhd-mode\u002FSKILL.md",[],[151,152,153,154,23,155,156,24,157,158,159,160,161,162,163,164,165,166,167,137],"adhd","mode","adhd mode","next","action","kit","output","style","progress","time","back","stop","session","reader","first","REST","harness",{"skillNo":169,"name":170,"nameZh":6,"description":171,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":172,"categories":173,"keywords":174,"publishedAt":39},"01M6KX463Z6E18EPDW873GDHKB","wait-what","That last message didn't land: re-explain it with the missing context.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fthinking\u002Fwait-what\u002FSKILL.md",[],[175,176,177,24,178,179,180,181,182,183,184],"wait","wait what","re","it","missing","message","context","explain","land","last",{"skillNo":186,"name":187,"nameZh":6,"description":188,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":189,"categories":190,"keywords":191,"publishedAt":39},"01M6KX43NE1NB0Y2HECY515730","to-questionnaire","Turn a decision you can't make alone into a questionnaire for the one person who can answer it, filled in async or together in a meeting.","https:\u002F\u002Fgithub.com\u002Fdougborg\u002Fharness-kit\u002Fblob\u002Fmain\u002Fskills\u002Fthinking\u002Fto-questionnaire\u002FSKILL.md",[],[192,193,23,194,195,196,197,87,198,178,199,200],"to questionnaire","questionnaire","person","can","answer","meeting","make","async","decision"]