[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CAHM5AYVDDB78YCNNNX8P3":3,"skill-same:01M6CAHM5AYVDDB78YCNNNX8P3":79},{"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":23,"publishedAt":37,"linkOnly":38,"markdownContent":39,"markdownBody":40,"frontMatter":41,"refName":52,"commitSha":53,"skillDirectory":54,"forksCount":55,"repositoryHtmlUrl":56,"repositoryHomepageUrl":6,"ownerHtmlUrl":57,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":58,"install":59,"resources":72},"01M6CAHM5AYVDDB78YCNNNX8P3","systematic-debugging",null,"4-phase root cause debugging: understand bugs before fixing.","adnichols\u002Fai-configs","adnichols","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F493746?v=4","01M6C33VRY9WF6XWYPT1AFA7JJ","Aaron Nichols","01M6C33VWTNKGRM92E9G643V4W",5,"MIT","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fprofiles\u002Fnerd\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36],"systematic debugging","debugging","macos","linux","test","windows","development","investigation","plan","troubleshooting","hermes","hermes agent","superpowers","2026-11-10 10:12:30",false,"---\nname: systematic-debugging\ndescription: \"4-phase root cause debugging: understand bugs before fixing.\"\nversion: 1.1.0\nauthor: Hermes Agent (adapted from obra\u002Fsuperpowers)\nlicense: MIT\nplatforms: [linux, macos, windows]\nmetadata:\n  hermes:\n    tags: [debugging, troubleshooting, problem-solving, root-cause, investigation]\n    related_skills: [test-driven-development, plan]\n---\n\n# 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## The Feedback Loop Rule\n\nThe feedback loop is the debugging work. Before reading code to build a theory, create or identify a **tight** command that can go red on the user's exact symptom and green when the bug is fixed. A tight loop is fast, deterministic, agent-runnable, and specific enough to catch this bug — not merely \"doesn't crash\".\n\nWhen a clean repro is hard, spend disproportionate effort building the loop. Guessing without a red-capable loop is the failure mode this skill exists to prevent.\n\n## When to Use\n\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- Someone 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---\n\n## Phase 1: Root Cause Investigation\n\n**BEFORE attempting ANY fix:**\n\n### 1. Read Error Messages Carefully\n\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\n**Action:** Use `read_file` on the relevant source files. Use `search_files` to find the error string in the codebase.\n\n### 2. Build a Tight Feedback Loop\n\n- Can you trigger the user's exact symptom with one command?\n- Does the command fail for this bug and only pass once the bug is fixed?\n- Is it fast enough to run repeatedly?\n- Is it deterministic? For flaky bugs, can you raise the reproduction rate high enough to debug?\n- If not reproducible → gather more data, don't guess.\n\n**Ways to construct a loop — try in roughly this order:**\n\n1. **Failing test** at the seam that reaches the bug: unit, integration, or end-to-end.\n2. **HTTP script \u002F curl** against a running dev server.\n3. **CLI invocation** with fixture input, diffing stdout\u002Fstderr against expected output.\n4. **Headless browser script** (Playwright\u002FPuppeteer) asserting on DOM, console, or network.\n5. **Replay a captured trace**: HAR, request payload, event log, queue message, or webhook body.\n6. **Throwaway harness** that boots the smallest useful slice of the system and calls the failing path.\n7. **Property \u002F fuzz loop** when the bug is intermittent wrong output over a broad input space.\n8. **Bisection harness** suitable for `git bisect run` when the bug appeared between two known states.\n9. **Differential loop** comparing old vs new version, two configs, two providers, or two datasets.\n10. **Human-in-the-loop script** only as a last resort: script the human steps and capture their result so the loop stays structured.\n\n**Tighten the loop once it exists:**\n\n- Make it faster: cache setup, narrow scope, skip unrelated initialization.\n- Make the signal sharper: assert the exact symptom, not generic success.\n- Make it more deterministic: pin time, seed randomness, isolate filesystem, freeze network.\n\nFor non-deterministic bugs, the immediate goal is a higher reproduction rate, not perfection. Run the trigger 100x, parallelize, add stress, narrow timing windows, or inject sleeps. A 50% flake is debuggable; a 1% flake usually is not.\n\n**Action:** Use the `terminal` tool to run the tight loop:\n\n```bash\n# Run a specific failing test\npytest tests\u002Ftest_module.py::test_name -v\n\n# Or run a scripted repro\npython scripts\u002Frepro_bug.py\n\n# Or run a high-repetition flaky repro\nfor i in {1..100}; do pytest tests\u002Ftest_flake.py::test_name -q || break; done\n```\n\n### 3. Check Recent Changes\n\n- What changed that could cause this?\n- Git diff, recent commits\n- New dependencies, config changes\n\n**Action:**\n\n```bash\n# Recent commits\ngit log --oneline -10\n\n# Uncommitted changes\ngit diff\n\n# Changes in specific file\ngit log -p --follow src\u002Fproblematic_file.py | head -100\n```\n\n### 4. Gather Evidence in Multi-Component Systems\n\n**WHEN system has multiple components (API → service → database, CI → build → deploy):**\n\n**BEFORE proposing fixes, add diagnostic instrumentation:**\n\nFor EACH component boundary:\n- Log what data enters the component\n- Log what data exits the component\n- Verify environment\u002Fconfig propagation\n- Check state at each layer\n\nRun once to gather evidence showing WHERE it breaks.\nTHEN analyze evidence to identify the failing component.\nTHEN investigate that specific component.\n\n### 5. Trace Data Flow\n\n**WHEN error is deep in the call stack:**\n\n- Where does the bad value originate?\n- What called this function with the bad value?\n- Keep tracing upstream until you find the source\n- Fix at the source, not at the symptom\n\n**Action:** Use `search_files` to trace references:\n\n```python\n# Find where the function is called\nsearch_files(\"function_name(\", path=\"src\u002F\", file_glob=\"*.py\")\n\n# Find where the variable is set\nsearch_files(\"variable_name\\\\s*=\", path=\"src\u002F\", file_glob=\"*.py\")\n```\n\n### Phase 1 Completion Checklist\n\n- [ ] Error messages fully read and understood\n- [ ] A tight loop command exists and has been run at least once\n- [ ] Loop is red-capable: it asserts the user's exact symptom, not a nearby failure\n- [ ] Loop is deterministic, or a flaky bug has a high enough reproduction rate to debug\n- [ ] Recent changes identified and reviewed\n- [ ] Evidence gathered (logs, state, data flow)\n- [ ] Problem isolated to specific component\u002Fcode\n- [ ] Root cause hypotheses can be stated and tested\n\n**STOP:** Do not proceed to Phase 2 until you understand WHY it's happening.\n\n---\n\n## Phase 2: Pattern Analysis\n\n**Find the pattern before fixing:**\n\n### 0. Minimize the Reproduction\n\nOnce the loop is red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut. Keep only what is load-bearing for the failure.\n\nDone when removing any remaining element makes the loop go green. A minimal repro narrows the hypothesis space and often becomes the cleanest regression test.\n\n### 1. Find Working Examples\n\n- Locate similar working code in the same codebase\n- What works that's similar to what's broken?\n\n**Action:** Use `search_files` to find comparable patterns:\n\n```python\nsearch_files(\"similar_pattern\", path=\"src\u002F\", file_glob=\"*.py\")\n```\n\n### 2. Compare Against References\n\n- If implementing a pattern, read the reference implementation COMPLETELY\n- Don't skim — read every line\n- Understand the pattern fully before applying\n\n### 3. Identify Differences\n\n- What's different between working and broken?\n- List every difference, however small\n- Don't assume \"that can't matter\"\n\n### 4. Understand Dependencies\n\n- What other components does this need?\n- What settings, config, environment?\n- What assumptions does it make?\n\n---\n\n## Phase 3: Hypothesis and Testing\n\n**Scientific method:**\n\n### 1. Form Ranked Falsifiable Hypotheses\n\n- Generate 3–5 plausible hypotheses before testing any single one.\n- Rank them by likelihood and cheapness to falsify.\n- State the prediction each hypothesis makes: \"If X is the cause, then changing or observing Y should make Z happen.\"\n- Discard or sharpen any hypothesis that does not make a testable prediction.\n\nIf the user is present, show the ranked list before testing. They may have domain knowledge that instantly re-ranks it. If the user is AFK, proceed with your ranking.\n\n### 2. Test Minimally\n\n- Test the highest-ranked hypothesis with the smallest possible probe.\n- Change one variable at a time.\n- Don't fix multiple things at once.\n- Prefer debugger\u002FREPL inspection when available; one breakpoint beats ten logs.\n- If you add logs, tag every temporary line with a unique prefix such as `[DEBUG-a4f2]` so cleanup is a single search.\n\n### 3. Verify Before Continuing\n\n- Did it work? → Phase 4\n- Didn't work? → Form NEW hypothesis\n- DON'T add more fixes on top\n\n### 4. When You Don't Know\n\n- Say \"I don't understand X\"\n- Don't pretend to know\n- Ask the user for help\n- Research more\n\n---\n\n## Phase 4: Implementation\n\n**Fix the root cause, not the symptom:**\n\n### 1. Create Failing Test Case\n\n- Simplest possible reproduction\n- Automated test if possible\n- MUST have before fixing\n- Use the `test-driven-development` skill\n\n### 2. Implement Single Fix\n\n- Address the root cause identified\n- ONE change at a time\n- No \"while I'm here\" improvements\n- No bundled refactoring\n\n### 3. Verify Fix\n\n```bash\n# Run the specific regression test\npytest tests\u002Ftest_module.py::test_regression -v\n\n# Run full suite — no regressions\npytest tests\u002F -q\n```\n\n### 4. If Fix Doesn't Work — The Rule of Three\n\n- **STOP.**\n- Count: How many fixes have you tried?\n- If \u003C 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\n### 5. If 3+ Fixes Failed: Question Architecture\n\n**Pattern indicating an architectural problem:**\n- Each fix reveals new shared state\u002Fcoupling in a 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 the architecture vs. continue fixing symptoms?\n\n**Discuss with the user before attempting more fixes.**\n\nThis is NOT a failed hypothesis — this is a wrong architecture.\n\n---\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 a new problem in a different place**\n\n**ALL of these mean: STOP. Return to Phase 1.**\n\n**If 3+ fixes failed:** Question the architecture (Phase 4 step 5).\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 the 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, trace data flow | Understand WHAT and WHY |\n| **2. Pattern** | Find working examples, compare, identify differences | Know what's different |\n| **3. Hypothesis** | Form theory, test minimally, one variable at a time | Confirmed or new hypothesis |\n| **4. Implementation** | Create regression test, fix root cause, verify | Bug resolved, all tests pass |\n\n## Hermes Agent Integration\n\n### Investigation Tools\n\nUse these Hermes tools during Phase 1:\n\n- **`search_files`** — Find error strings, trace function calls, locate patterns\n- **`read_file`** — Read source code with line numbers for precise analysis\n- **`terminal`** — Run tests, check git history, reproduce bugs\n- **`web_search`\u002F`web_extract`** — Research error messages, library docs\n\n### Direct investigation\n\nKeep debugging in the driving session so hypotheses, experiments, and fixes share one evidence trail. Use direct search, reads, reproduction commands, and targeted instrumentation. If an explicitly read-only helper is used for a bounded evidence question, the driving agent still owns diagnosis and all fixes.\n\n### With test-driven-development\n\nWhen fixing bugs:\n1. Write a test that reproduces the bug (RED)\n2. Debug systematically to find root cause\n3. Fix the root cause (GREEN)\n4. The test proves the fix and prevents regression\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**No shortcuts. No guessing. Systematic always wins.**\n","# 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## The Feedback Loop Rule\n\nThe feedback loop is the debugging work. Before reading code to build a theory, create or identify a **tight** command that can go red on the user's exact symptom and green when the bug is fixed. A tight loop is fast, deterministic, agent-runnable, and specific enough to catch this bug — not merely \"doesn't crash\".\n\nWhen a clean repro is hard, spend disproportionate effort building the loop. Guessing without a red-capable loop is the failure mode this skill exists to prevent.\n\n## When to Use\n\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- Someone 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---\n\n## Phase 1: Root Cause Investigation\n\n**BEFORE attempting ANY fix:**\n\n### 1. Read Error Messages Carefully\n\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\n**Action:** Use `read_file` on the relevant source files. Use `search_files` to find the error string in the codebase.\n\n### 2. Build a Tight Feedback Loop\n\n- Can you trigger the user's exact symptom with one command?\n- Does the command fail for this bug and only pass once the bug is fixed?\n- Is it fast enough to run repeatedly?\n- Is it deterministic? For flaky bugs, can you raise the reproduction rate high enough to debug?\n- If not reproducible → gather more data, don't guess.\n\n**Ways to construct a loop — try in roughly this order:**\n\n1. **Failing test** at the seam that reaches the bug: unit, integration, or end-to-end.\n2. **HTTP script \u002F curl** against a running dev server.\n3. **CLI invocation** with fixture input, diffing stdout\u002Fstderr against expected output.\n4. **Headless browser script** (Playwright\u002FPuppeteer) asserting on DOM, console, or network.\n5. **Replay a captured trace**: HAR, request payload, event log, queue message, or webhook body.\n6. **Throwaway harness** that boots the smallest useful slice of the system and calls the failing path.\n7. **Property \u002F fuzz loop** when the bug is intermittent wrong output over a broad input space.\n8. **Bisection harness** suitable for `git bisect run` when the bug appeared between two known states.\n9. **Differential loop** comparing old vs new version, two configs, two providers, or two datasets.\n10. **Human-in-the-loop script** only as a last resort: script the human steps and capture their result so the loop stays structured.\n\n**Tighten the loop once it exists:**\n\n- Make it faster: cache setup, narrow scope, skip unrelated initialization.\n- Make the signal sharper: assert the exact symptom, not generic success.\n- Make it more deterministic: pin time, seed randomness, isolate filesystem, freeze network.\n\nFor non-deterministic bugs, the immediate goal is a higher reproduction rate, not perfection. Run the trigger 100x, parallelize, add stress, narrow timing windows, or inject sleeps. A 50% flake is debuggable; a 1% flake usually is not.\n\n**Action:** Use the `terminal` tool to run the tight loop:\n\n```bash\n# Run a specific failing test\npytest tests\u002Ftest_module.py::test_name -v\n\n# Or run a scripted repro\npython scripts\u002Frepro_bug.py\n\n# Or run a high-repetition flaky repro\nfor i in {1..100}; do pytest tests\u002Ftest_flake.py::test_name -q || break; done\n```\n\n### 3. Check Recent Changes\n\n- What changed that could cause this?\n- Git diff, recent commits\n- New dependencies, config changes\n\n**Action:**\n\n```bash\n# Recent commits\ngit log --oneline -10\n\n# Uncommitted changes\ngit diff\n\n# Changes in specific file\ngit log -p --follow src\u002Fproblematic_file.py | head -100\n```\n\n### 4. Gather Evidence in Multi-Component Systems\n\n**WHEN system has multiple components (API → service → database, CI → build → deploy):**\n\n**BEFORE proposing fixes, add diagnostic instrumentation:**\n\nFor EACH component boundary:\n- Log what data enters the component\n- Log what data exits the component\n- Verify environment\u002Fconfig propagation\n- Check state at each layer\n\nRun once to gather evidence showing WHERE it breaks.\nTHEN analyze evidence to identify the failing component.\nTHEN investigate that specific component.\n\n### 5. Trace Data Flow\n\n**WHEN error is deep in the call stack:**\n\n- Where does the bad value originate?\n- What called this function with the bad value?\n- Keep tracing upstream until you find the source\n- Fix at the source, not at the symptom\n\n**Action:** Use `search_files` to trace references:\n\n```python\n# Find where the function is called\nsearch_files(\"function_name(\", path=\"src\u002F\", file_glob=\"*.py\")\n\n# Find where the variable is set\nsearch_files(\"variable_name\\\\s*=\", path=\"src\u002F\", file_glob=\"*.py\")\n```\n\n### Phase 1 Completion Checklist\n\n- [ ] Error messages fully read and understood\n- [ ] A tight loop command exists and has been run at least once\n- [ ] Loop is red-capable: it asserts the user's exact symptom, not a nearby failure\n- [ ] Loop is deterministic, or a flaky bug has a high enough reproduction rate to debug\n- [ ] Recent changes identified and reviewed\n- [ ] Evidence gathered (logs, state, data flow)\n- [ ] Problem isolated to specific component\u002Fcode\n- [ ] Root cause hypotheses can be stated and tested\n\n**STOP:** Do not proceed to Phase 2 until you understand WHY it's happening.\n\n---\n\n## Phase 2: Pattern Analysis\n\n**Find the pattern before fixing:**\n\n### 0. Minimize the Reproduction\n\nOnce the loop is red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut. Keep only what is load-bearing for the failure.\n\nDone when removing any remaining element makes the loop go green. A minimal repro narrows the hypothesis space and often becomes the cleanest regression test.\n\n### 1. Find Working Examples\n\n- Locate similar working code in the same codebase\n- What works that's similar to what's broken?\n\n**Action:** Use `search_files` to find comparable patterns:\n\n```python\nsearch_files(\"similar_pattern\", path=\"src\u002F\", file_glob=\"*.py\")\n```\n\n### 2. Compare Against References\n\n- If implementing a pattern, read the reference implementation COMPLETELY\n- Don't skim — read every line\n- Understand the pattern fully before applying\n\n### 3. Identify Differences\n\n- What's different between working and broken?\n- List every difference, however small\n- Don't assume \"that can't matter\"\n\n### 4. Understand Dependencies\n\n- What other components does this need?\n- What settings, config, environment?\n- What assumptions does it make?\n\n---\n\n## Phase 3: Hypothesis and Testing\n\n**Scientific method:**\n\n### 1. Form Ranked Falsifiable Hypotheses\n\n- Generate 3–5 plausible hypotheses before testing any single one.\n- Rank them by likelihood and cheapness to falsify.\n- State the prediction each hypothesis makes: \"If X is the cause, then changing or observing Y should make Z happen.\"\n- Discard or sharpen any hypothesis that does not make a testable prediction.\n\nIf the user is present, show the ranked list before testing. They may have domain knowledge that instantly re-ranks it. If the user is AFK, proceed with your ranking.\n\n### 2. Test Minimally\n\n- Test the highest-ranked hypothesis with the smallest possible probe.\n- Change one variable at a time.\n- Don't fix multiple things at once.\n- Prefer debugger\u002FREPL inspection when available; one breakpoint beats ten logs.\n- If you add logs, tag every temporary line with a unique prefix such as `[DEBUG-a4f2]` so cleanup is a single search.\n\n### 3. Verify Before Continuing\n\n- Did it work? → Phase 4\n- Didn't work? → Form NEW hypothesis\n- DON'T add more fixes on top\n\n### 4. When You Don't Know\n\n- Say \"I don't understand X\"\n- Don't pretend to know\n- Ask the user for help\n- Research more\n\n---\n\n## Phase 4: Implementation\n\n**Fix the root cause, not the symptom:**\n\n### 1. Create Failing Test Case\n\n- Simplest possible reproduction\n- Automated test if possible\n- MUST have before fixing\n- Use the `test-driven-development` skill\n\n### 2. Implement Single Fix\n\n- Address the root cause identified\n- ONE change at a time\n- No \"while I'm here\" improvements\n- No bundled refactoring\n\n### 3. Verify Fix\n\n```bash\n# Run the specific regression test\npytest tests\u002Ftest_module.py::test_regression -v\n\n# Run full suite — no regressions\npytest tests\u002F -q\n```\n\n### 4. If Fix Doesn't Work — The Rule of Three\n\n- **STOP.**\n- Count: How many fixes have you tried?\n- If \u003C 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\n### 5. If 3+ Fixes Failed: Question Architecture\n\n**Pattern indicating an architectural problem:**\n- Each fix reveals new shared state\u002Fcoupling in a 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 the architecture vs. continue fixing symptoms?\n\n**Discuss with the user before attempting more fixes.**\n\nThis is NOT a failed hypothesis — this is a wrong architecture.\n\n---\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 a new problem in a different place**\n\n**ALL of these mean: STOP. Return to Phase 1.**\n\n**If 3+ fixes failed:** Question the architecture (Phase 4 step 5).\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 the 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, trace data flow | Understand WHAT and WHY |\n| **2. Pattern** | Find working examples, compare, identify differences | Know what's different |\n| **3. Hypothesis** | Form theory, test minimally, one variable at a time | Confirmed or new hypothesis |\n| **4. Implementation** | Create regression test, fix root cause, verify | Bug resolved, all tests pass |\n\n## Hermes Agent Integration\n\n### Investigation Tools\n\nUse these Hermes tools during Phase 1:\n\n- **`search_files`** — Find error strings, trace function calls, locate patterns\n- **`read_file`** — Read source code with line numbers for precise analysis\n- **`terminal`** — Run tests, check git history, reproduce bugs\n- **`web_search`\u002F`web_extract`** — Research error messages, library docs\n\n### Direct investigation\n\nKeep debugging in the driving session so hypotheses, experiments, and fixes share one evidence trail. Use direct search, reads, reproduction commands, and targeted instrumentation. If an explicitly read-only helper is used for a bounded evidence question, the driving agent still owns diagnosis and all fixes.\n\n### With test-driven-development\n\nWhen fixing bugs:\n1. Write a test that reproduces the bug (RED)\n2. Debug systematically to find root cause\n3. Fix the root cause (GREEN)\n4. The test proves the fix and prevents regression\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**No shortcuts. No guessing. Systematic always wins.**\n",{"name":5,"author":42,"license":15,"version":43,"metadata":44,"platforms":51,"description":7},"Hermes Agent (adapted from obra\u002Fsuperpowers)","1.1.0",{"hermes":45},{"tags":46,"related_skills":49},[25,33,47,48,31],"problem-solving","root-cause",[50,32],"test-driven-development",[27,26,29],"main","64e2fc9afa7bb3da1138eb73399144d0e7e73e9d","_hermes\u002Fdefault\u002Fprofiles\u002Fnerd\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging",4,"https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs","https:\u002F\u002Fgithub.com\u002Fadnichols","2026-11-06 00:28:38",{"source":8,"skillName":5,"commands":60,"prompt":70,"zipAvailable":71},[61,64,67],{"tool":62,"command":63},"npx","npx skills add adnichols\u002Fai-configs --skill systematic-debugging",{"tool":65,"command":66},"bunx","bunx skills add adnichols\u002Fai-configs --skill systematic-debugging",{"tool":68,"command":69},"pnpm","pnpm dlx skills add adnichols\u002Fai-configs --skill systematic-debugging","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fprofiles\u002Fnerd\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",true,[73],{"path":74,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":77,"sourceHtmlUrl":78},"references\u002Fdetailed-guide.md","REFERENCE","参考文档",30270,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-youtube-seo-optimizer\u002Freferences\u002Fdetailed-guide.md",[80,97,126,146,152,168],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":37},"01M6CB7RN791P5RRRCJWWC7DAR","blocked-page-recovery","Use when a fetch fails: 403\u002F429, paywall, WAF, bot wall.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fweb\u002Fblocked-page-recovery\u002FSKILL.md",[],[87,88,89,90,91,92,93,35,34,94,95,29,96,27,26],"recovery","page","blocked page recovery","bot","fallback","use","fetch","Citations","waf","research",{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":114,"publishedAt":37},"01M6CB7NQY2VVYCQJ1QBXACQF4","writing-plans","Use when creating or updating executable software plans. Keep plans as local files unless the user explicitly asks to register them in Doct.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fwriting-plans\u002FSKILL.md",[103,106,109],{"categoryNo":104,"categoryName":105,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":107,"categoryName":108,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":110,"categoryName":111,"taxonomyType":112,"taxonomyTypeDesc":113},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[115,116,117,28,118,119,120,30,121,122,123,124,92,125,35,34,32],"writing","writing plans","documentation","workflow","design","user","planning","files","implementation","html","ops",{"skillNo":127,"name":50,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":138,"publishedAt":37},"01M6CB7JME246KZQHP73Z2STDF","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[131,134,135],{"categoryNo":132,"categoryName":133,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000007","代码审查",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":136,"categoryName":137,"taxonomyType":112,"taxonomyTypeDesc":113},"01JBSEEDCAT000000000000037","律师与法务",[28,30,139,140,36,35,34,141,32,142,143,25,26,144,27,145,29],"test driven development","red-green-refactor","quality","refactor","code","tdd","testing",{"skillNo":147,"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":148,"categories":149,"keywords":151,"publishedAt":37},"01M6CB7FQ407KQTD4Z9VAWKY54","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[150],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[25,24,30,36,35,34,33,32,31,29,28,27,26],{"skillNo":153,"name":154,"nameZh":6,"description":155,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":156,"categories":157,"keywords":161,"publishedAt":37},"01M6CB7D57MK88HE5YPZHKH68Q","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[158],{"categoryNo":159,"categoryName":160,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",[154,29,162,163,96,164,27,26,165,166,167,35,34,32,121],"validate","experiments","prototype","feasibility","sketch","experiment",{"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":178,"publishedAt":37},"01M6CB7APAQ37YE5YE1MAAFT42","simplify-code","Parallel 3-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002Fadnichols\u002Fai-configs\u002Fblob\u002Fmain\u002F_hermes\u002Fdefault\u002Fskills\u002Fsoftware-development\u002Fsimplify-code\u002FSKILL.md",[174,175],{"categoryNo":107,"categoryName":108,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":176,"categoryName":177,"taxonomyType":112,"taxonomyTypeDesc":113},"01JBSEEDCAT000000000000030","开发工程师",[179,180,143,181,35,34,182,32,142,183,184,185,30,29,28,27,186,26],"simplify code","simplify","subagent","parallel","code-review","delegation","cleanup","review"]