[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F7SPKQBVBPCKCVJGND0S98":3,"skill-same:01M7F7SPKQBVBPCKCVJGND0S98":63},{"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":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":14,"repositoryHtmlUrl":44,"repositoryHomepageUrl":6,"ownerHtmlUrl":45,"ownerBlogUrl":46,"ownerDescription":47,"updatedAt":48,"install":49,"resources":62},"01M7F7SPKQBVBPCKCVJGND0S98","systematic-debugging",null,"4-phase root cause debugging: understand bugs before fixing.","chaorenex1\u002Fhermes-home-content","chaorenex1","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F23194925?v=4","01M7F5NA1D1D02R2MEMYQN2NZT","chan chan","01M7F5NA20KTHMTY2015CYM1TZ",0,"MIT","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\r\nname: systematic-debugging\r\ndescription: \"4-phase root cause debugging: understand bugs before fixing.\"\r\nversion: 1.1.0\r\nauthor: Hermes Agent (adapted from obra\u002Fsuperpowers)\r\nlicense: MIT\r\nplatforms: [linux, macos, windows]\r\nmetadata:\r\n  hermes:\r\n    tags: [debugging, troubleshooting, problem-solving, root-cause, investigation]\r\n    related_skills: [test-driven-development, subagent-driven-development]\r\n---\r\n\r\n# Systematic Debugging\r\n\r\n## Overview\r\n\r\nRandom fixes waste time and create new bugs. Quick patches mask underlying issues.\r\n\r\n**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.\r\n\r\n**Violating the letter of this process is violating the spirit of debugging.**\r\n\r\n## The Iron Law\r\n\r\n```\r\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\r\n```\r\n\r\nIf you haven't completed Phase 1, you cannot propose fixes.\r\n\r\n## The Feedback Loop Rule\r\n\r\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\".\r\n\r\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.\r\n\r\n## When to Use\r\n\r\nUse for ANY technical issue:\r\n- Test failures\r\n- Bugs in production\r\n- Unexpected behavior\r\n- Performance problems\r\n- Build failures\r\n- Integration issues\r\n\r\n**Use this ESPECIALLY when:**\r\n- Under time pressure (emergencies make guessing tempting)\r\n- \"Just one quick fix\" seems obvious\r\n- You've already tried multiple fixes\r\n- Previous fix didn't work\r\n- You don't fully understand the issue\r\n\r\n**Don't skip when:**\r\n- Issue seems simple (simple bugs have root causes too)\r\n- You're in a hurry (rushing guarantees rework)\r\n- Someone wants it fixed NOW (systematic is faster than thrashing)\r\n\r\n## The Four Phases\r\n\r\nYou MUST complete each phase before proceeding to the next.\r\n\r\n---\r\n\r\n## Phase 1: Root Cause Investigation\r\n\r\n**BEFORE attempting ANY fix:**\r\n\r\n### 1. Read Error Messages Carefully\r\n\r\n- Don't skip past errors or warnings\r\n- They often contain the exact solution\r\n- Read stack traces completely\r\n- Note line numbers, file paths, error codes\r\n\r\n**Action:** Use `read_file` on the relevant source files. Use `search_files` to find the error string in the codebase.\r\n\r\n### 2. Build a Tight Feedback Loop\r\n\r\n- Can you trigger the user's exact symptom with one command?\r\n- Does the command fail for this bug and only pass once the bug is fixed?\r\n- Is it fast enough to run repeatedly?\r\n- Is it deterministic? For flaky bugs, can you raise the reproduction rate high enough to debug?\r\n- If not reproducible → gather more data, don't guess.\r\n\r\n**Ways to construct a loop — try in roughly this order:**\r\n\r\n1. **Failing test** at the seam that reaches the bug: unit, integration, or end-to-end.\r\n2. **HTTP script \u002F curl** against a running dev server.\r\n3. **CLI invocation** with fixture input, diffing stdout\u002Fstderr against expected output.\r\n4. **Headless browser script** (Playwright\u002FPuppeteer) asserting on DOM, console, or network.\r\n5. **Replay a captured trace**: HAR, request payload, event log, queue message, or webhook body.\r\n6. **Throwaway harness** that boots the smallest useful slice of the system and calls the failing path.\r\n7. **Property \u002F fuzz loop** when the bug is intermittent wrong output over a broad input space.\r\n8. **Bisection harness** suitable for `git bisect run` when the bug appeared between two known states.\r\n9. **Differential loop** comparing old vs new version, two configs, two providers, or two datasets.\r\n10. **Human-in-the-loop script** only as a last resort: script the human steps and capture their result so the loop stays structured.\r\n\r\n**Tighten the loop once it exists:**\r\n\r\n- Make it faster: cache setup, narrow scope, skip unrelated initialization.\r\n- Make the signal sharper: assert the exact symptom, not generic success.\r\n- Make it more deterministic: pin time, seed randomness, isolate filesystem, freeze network.\r\n\r\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.\r\n\r\n**Action:** Use the `terminal` tool to run the tight loop:\r\n\r\n```bash\r\n# Run a specific failing test\r\npytest tests\u002Ftest_module.py::test_name -v\r\n\r\n# Or run a scripted repro\r\npython scripts\u002Frepro_bug.py\r\n\r\n# Or run a high-repetition flaky repro\r\nfor i in {1..100}; do pytest tests\u002Ftest_flake.py::test_name -q || break; done\r\n```\r\n\r\n### 3. Check Recent Changes\r\n\r\n- What changed that could cause this?\r\n- Git diff, recent commits\r\n- New dependencies, config changes\r\n\r\n**Action:**\r\n\r\n```bash\r\n# Recent commits\r\ngit log --oneline -10\r\n\r\n# Uncommitted changes\r\ngit diff\r\n\r\n# Changes in specific file\r\ngit log -p --follow src\u002Fproblematic_file.py | head -100\r\n```\r\n\r\n### 4. Gather Evidence in Multi-Component Systems\r\n\r\n**WHEN system has multiple components (API → service → database, CI → build → deploy):**\r\n\r\n**BEFORE proposing fixes, add diagnostic instrumentation:**\r\n\r\nFor EACH component boundary:\r\n- Log what data enters the component\r\n- Log what data exits the component\r\n- Verify environment\u002Fconfig propagation\r\n- Check state at each layer\r\n\r\nRun once to gather evidence showing WHERE it breaks.\r\nTHEN analyze evidence to identify the failing component.\r\nTHEN investigate that specific component.\r\n\r\n### 5. Trace Data Flow\r\n\r\n**WHEN error is deep in the call stack:**\r\n\r\n- Where does the bad value originate?\r\n- What called this function with the bad value?\r\n- Keep tracing upstream until you find the source\r\n- Fix at the source, not at the symptom\r\n\r\n**Action:** Use `search_files` to trace references:\r\n\r\n```python\r\n# Find where the function is called\r\nsearch_files(\"function_name(\", path=\"src\u002F\", file_glob=\"*.py\")\r\n\r\n# Find where the variable is set\r\nsearch_files(\"variable_name\\\\s*=\", path=\"src\u002F\", file_glob=\"*.py\")\r\n```\r\n\r\n### Phase 1 Completion Checklist\r\n\r\n- [ ] Error messages fully read and understood\r\n- [ ] A tight loop command exists and has been run at least once\r\n- [ ] Loop is red-capable: it asserts the user's exact symptom, not a nearby failure\r\n- [ ] Loop is deterministic, or a flaky bug has a high enough reproduction rate to debug\r\n- [ ] Recent changes identified and reviewed\r\n- [ ] Evidence gathered (logs, state, data flow)\r\n- [ ] Problem isolated to specific component\u002Fcode\r\n- [ ] Root cause hypotheses can be stated and tested\r\n\r\n**STOP:** Do not proceed to Phase 2 until you understand WHY it's happening.\r\n\r\n---\r\n\r\n## Phase 2: Pattern Analysis\r\n\r\n**Find the pattern before fixing:**\r\n\r\n### 0. Minimize the Reproduction\r\n\r\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.\r\n\r\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.\r\n\r\n### 1. Find Working Examples\r\n\r\n- Locate similar working code in the same codebase\r\n- What works that's similar to what's broken?\r\n\r\n**Action:** Use `search_files` to find comparable patterns:\r\n\r\n```python\r\nsearch_files(\"similar_pattern\", path=\"src\u002F\", file_glob=\"*.py\")\r\n```\r\n\r\n### 2. Compare Against References\r\n\r\n- If implementing a pattern, read the reference implementation COMPLETELY\r\n- Don't skim — read every line\r\n- Understand the pattern fully before applying\r\n\r\n### 3. Identify Differences\r\n\r\n- What's different between working and broken?\r\n- List every difference, however small\r\n- Don't assume \"that can't matter\"\r\n\r\n### 4. Understand Dependencies\r\n\r\n- What other components does this need?\r\n- What settings, config, environment?\r\n- What assumptions does it make?\r\n\r\n---\r\n\r\n## Phase 3: Hypothesis and Testing\r\n\r\n**Scientific method:**\r\n\r\n### 1. Form Ranked Falsifiable Hypotheses\r\n\r\n- Generate 3–5 plausible hypotheses before testing any single one.\r\n- Rank them by likelihood and cheapness to falsify.\r\n- State the prediction each hypothesis makes: \"If X is the cause, then changing or observing Y should make Z happen.\"\r\n- Discard or sharpen any hypothesis that does not make a testable prediction.\r\n\r\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.\r\n\r\n### 2. Test Minimally\r\n\r\n- Test the highest-ranked hypothesis with the smallest possible probe.\r\n- Change one variable at a time.\r\n- Don't fix multiple things at once.\r\n- Prefer debugger\u002FREPL inspection when available; one breakpoint beats ten logs.\r\n- If you add logs, tag every temporary line with a unique prefix such as `[DEBUG-a4f2]` so cleanup is a single search.\r\n\r\n### 3. Verify Before Continuing\r\n\r\n- Did it work? → Phase 4\r\n- Didn't work? → Form NEW hypothesis\r\n- DON'T add more fixes on top\r\n\r\n### 4. When You Don't Know\r\n\r\n- Say \"I don't understand X\"\r\n- Don't pretend to know\r\n- Ask the user for help\r\n- Research more\r\n\r\n---\r\n\r\n## Phase 4: Implementation\r\n\r\n**Fix the root cause, not the symptom:**\r\n\r\n### 1. Create Failing Test Case\r\n\r\n- Simplest possible reproduction\r\n- Automated test if possible\r\n- MUST have before fixing\r\n- Use the `test-driven-development` skill\r\n\r\n### 2. Implement Single Fix\r\n\r\n- Address the root cause identified\r\n- ONE change at a time\r\n- No \"while I'm here\" improvements\r\n- No bundled refactoring\r\n\r\n### 3. Verify Fix\r\n\r\n```bash\r\n# Run the specific regression test\r\npytest tests\u002Ftest_module.py::test_regression -v\r\n\r\n# Run full suite — no regressions\r\npytest tests\u002F -q\r\n```\r\n\r\n### 4. If Fix Doesn't Work — The Rule of Three\r\n\r\n- **STOP.**\r\n- Count: How many fixes have you tried?\r\n- If \u003C 3: Return to Phase 1, re-analyze with new information\r\n- **If ≥ 3: STOP and question the architecture (step 5 below)**\r\n- DON'T attempt Fix #4 without architectural discussion\r\n\r\n### 5. If 3+ Fixes Failed: Question Architecture\r\n\r\n**Pattern indicating an architectural problem:**\r\n- Each fix reveals new shared state\u002Fcoupling in a different place\r\n- Fixes require \"massive refactoring\" to implement\r\n- Each fix creates new symptoms elsewhere\r\n\r\n**STOP and question fundamentals:**\r\n- Is this pattern fundamentally sound?\r\n- Are we \"sticking with it through sheer inertia\"?\r\n- Should we refactor the architecture vs. continue fixing symptoms?\r\n\r\n**Discuss with the user before attempting more fixes.**\r\n\r\nThis is NOT a failed hypothesis — this is a wrong architecture.\r\n\r\n---\r\n\r\n## Red Flags — STOP and Follow Process\r\n\r\nIf you catch yourself thinking:\r\n- \"Quick fix for now, investigate later\"\r\n- \"Just try changing X and see if it works\"\r\n- \"Add multiple changes, run tests\"\r\n- \"Skip the test, I'll manually verify\"\r\n- \"It's probably X, let me fix that\"\r\n- \"I don't fully understand but this might work\"\r\n- \"Pattern says X but I'll adapt it differently\"\r\n- \"Here are the main problems: [lists fixes without investigation]\"\r\n- Proposing solutions before tracing data flow\r\n- **\"One more fix attempt\" (when already tried 2+)**\r\n- **Each fix reveals a new problem in a different place**\r\n\r\n**ALL of these mean: STOP. Return to Phase 1.**\r\n\r\n**If 3+ fixes failed:** Question the architecture (Phase 4 step 5).\r\n\r\n## Common Rationalizations\r\n\r\n| Excuse | Reality |\r\n|--------|---------|\r\n| \"Issue is simple, don't need process\" | Simple issues have root causes too. Process is fast for simple bugs. |\r\n| \"Emergency, no time for process\" | Systematic debugging is FASTER than guess-and-check thrashing. |\r\n| \"Just try this first, then investigate\" | First fix sets the pattern. Do it right from the start. |\r\n| \"I'll write test after confirming fix works\" | Untested fixes don't stick. Test first proves it. |\r\n| \"Multiple fixes at once saves time\" | Can't isolate what worked. Causes new bugs. |\r\n| \"Reference too long, I'll adapt the pattern\" | Partial understanding guarantees bugs. Read it completely. |\r\n| \"I see the problem, let me fix it\" | Seeing symptoms ≠ understanding root cause. |\r\n| \"One more fix attempt\" (after 2+ failures) | 3+ failures = architectural problem. Question the pattern, don't fix again. |\r\n\r\n## Quick Reference\r\n\r\n| Phase | Key Activities | Success Criteria |\r\n|-------|---------------|------------------|\r\n| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence, trace data flow | Understand WHAT and WHY |\r\n| **2. Pattern** | Find working examples, compare, identify differences | Know what's different |\r\n| **3. Hypothesis** | Form theory, test minimally, one variable at a time | Confirmed or new hypothesis |\r\n| **4. Implementation** | Create regression test, fix root cause, verify | Bug resolved, all tests pass |\r\n\r\n## Hermes Agent Integration\r\n\r\n### Investigation Tools\r\n\r\nUse these Hermes tools during Phase 1:\r\n\r\n- **`search_files`** — Find error strings, trace function calls, locate patterns\r\n- **`read_file`** — Read source code with line numbers for precise analysis\r\n- **`terminal`** — Run tests, check git history, reproduce bugs\r\n- **`web_search`\u002F`web_extract`** — Research error messages, library docs\r\n\r\n### With delegate_task\r\n\r\nFor complex multi-component debugging, dispatch investigation subagents:\r\n\r\n```python\r\ndelegate_task(\r\n    goal=\"Investigate why [specific test\u002Fbehavior] fails\",\r\n    context=\"\"\"\r\n    Follow systematic-debugging skill:\r\n    1. Read the error message carefully\r\n    2. Reproduce the issue\r\n    3. Trace the data flow to find root cause\r\n    4. Report findings — do NOT fix yet\r\n\r\n    Error: [paste full error]\r\n    File: [path to failing code]\r\n    Test command: [exact command]\r\n    \"\"\",\r\n    toolsets=['terminal', 'file']\r\n)\r\n```\r\n\r\n### With test-driven-development\r\n\r\nWhen fixing bugs:\r\n1. Write a test that reproduces the bug (RED)\r\n2. Debug systematically to find root cause\r\n3. Fix the root cause (GREEN)\r\n4. The test proves the fix and prevents regression\r\n\r\n## Real-World Impact\r\n\r\nFrom debugging sessions:\r\n- Systematic approach: 15-30 minutes to fix\r\n- Random fixes approach: 2-3 hours of thrashing\r\n- First-time fix rate: 95% vs 40%\r\n- New bugs introduced: Near zero vs common\r\n\r\n**No shortcuts. No guessing. Systematic always wins.**\r\n","# Systematic Debugging\r\n\r\n## Overview\r\n\r\nRandom fixes waste time and create new bugs. Quick patches mask underlying issues.\r\n\r\n**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.\r\n\r\n**Violating the letter of this process is violating the spirit of debugging.**\r\n\r\n## The Iron Law\r\n\r\n```\r\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\r\n```\r\n\r\nIf you haven't completed Phase 1, you cannot propose fixes.\r\n\r\n## The Feedback Loop Rule\r\n\r\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\".\r\n\r\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.\r\n\r\n## When to Use\r\n\r\nUse for ANY technical issue:\r\n- Test failures\r\n- Bugs in production\r\n- Unexpected behavior\r\n- Performance problems\r\n- Build failures\r\n- Integration issues\r\n\r\n**Use this ESPECIALLY when:**\r\n- Under time pressure (emergencies make guessing tempting)\r\n- \"Just one quick fix\" seems obvious\r\n- You've already tried multiple fixes\r\n- Previous fix didn't work\r\n- You don't fully understand the issue\r\n\r\n**Don't skip when:**\r\n- Issue seems simple (simple bugs have root causes too)\r\n- You're in a hurry (rushing guarantees rework)\r\n- Someone wants it fixed NOW (systematic is faster than thrashing)\r\n\r\n## The Four Phases\r\n\r\nYou MUST complete each phase before proceeding to the next.\r\n\r\n---\r\n\r\n## Phase 1: Root Cause Investigation\r\n\r\n**BEFORE attempting ANY fix:**\r\n\r\n### 1. Read Error Messages Carefully\r\n\r\n- Don't skip past errors or warnings\r\n- They often contain the exact solution\r\n- Read stack traces completely\r\n- Note line numbers, file paths, error codes\r\n\r\n**Action:** Use `read_file` on the relevant source files. Use `search_files` to find the error string in the codebase.\r\n\r\n### 2. Build a Tight Feedback Loop\r\n\r\n- Can you trigger the user's exact symptom with one command?\r\n- Does the command fail for this bug and only pass once the bug is fixed?\r\n- Is it fast enough to run repeatedly?\r\n- Is it deterministic? For flaky bugs, can you raise the reproduction rate high enough to debug?\r\n- If not reproducible → gather more data, don't guess.\r\n\r\n**Ways to construct a loop — try in roughly this order:**\r\n\r\n1. **Failing test** at the seam that reaches the bug: unit, integration, or end-to-end.\r\n2. **HTTP script \u002F curl** against a running dev server.\r\n3. **CLI invocation** with fixture input, diffing stdout\u002Fstderr against expected output.\r\n4. **Headless browser script** (Playwright\u002FPuppeteer) asserting on DOM, console, or network.\r\n5. **Replay a captured trace**: HAR, request payload, event log, queue message, or webhook body.\r\n6. **Throwaway harness** that boots the smallest useful slice of the system and calls the failing path.\r\n7. **Property \u002F fuzz loop** when the bug is intermittent wrong output over a broad input space.\r\n8. **Bisection harness** suitable for `git bisect run` when the bug appeared between two known states.\r\n9. **Differential loop** comparing old vs new version, two configs, two providers, or two datasets.\r\n10. **Human-in-the-loop script** only as a last resort: script the human steps and capture their result so the loop stays structured.\r\n\r\n**Tighten the loop once it exists:**\r\n\r\n- Make it faster: cache setup, narrow scope, skip unrelated initialization.\r\n- Make the signal sharper: assert the exact symptom, not generic success.\r\n- Make it more deterministic: pin time, seed randomness, isolate filesystem, freeze network.\r\n\r\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.\r\n\r\n**Action:** Use the `terminal` tool to run the tight loop:\r\n\r\n```bash\r\n# Run a specific failing test\r\npytest tests\u002Ftest_module.py::test_name -v\r\n\r\n# Or run a scripted repro\r\npython scripts\u002Frepro_bug.py\r\n\r\n# Or run a high-repetition flaky repro\r\nfor i in {1..100}; do pytest tests\u002Ftest_flake.py::test_name -q || break; done\r\n```\r\n\r\n### 3. Check Recent Changes\r\n\r\n- What changed that could cause this?\r\n- Git diff, recent commits\r\n- New dependencies, config changes\r\n\r\n**Action:**\r\n\r\n```bash\r\n# Recent commits\r\ngit log --oneline -10\r\n\r\n# Uncommitted changes\r\ngit diff\r\n\r\n# Changes in specific file\r\ngit log -p --follow src\u002Fproblematic_file.py | head -100\r\n```\r\n\r\n### 4. Gather Evidence in Multi-Component Systems\r\n\r\n**WHEN system has multiple components (API → service → database, CI → build → deploy):**\r\n\r\n**BEFORE proposing fixes, add diagnostic instrumentation:**\r\n\r\nFor EACH component boundary:\r\n- Log what data enters the component\r\n- Log what data exits the component\r\n- Verify environment\u002Fconfig propagation\r\n- Check state at each layer\r\n\r\nRun once to gather evidence showing WHERE it breaks.\r\nTHEN analyze evidence to identify the failing component.\r\nTHEN investigate that specific component.\r\n\r\n### 5. Trace Data Flow\r\n\r\n**WHEN error is deep in the call stack:**\r\n\r\n- Where does the bad value originate?\r\n- What called this function with the bad value?\r\n- Keep tracing upstream until you find the source\r\n- Fix at the source, not at the symptom\r\n\r\n**Action:** Use `search_files` to trace references:\r\n\r\n```python\r\n# Find where the function is called\r\nsearch_files(\"function_name(\", path=\"src\u002F\", file_glob=\"*.py\")\r\n\r\n# Find where the variable is set\r\nsearch_files(\"variable_name\\\\s*=\", path=\"src\u002F\", file_glob=\"*.py\")\r\n```\r\n\r\n### Phase 1 Completion Checklist\r\n\r\n- [ ] Error messages fully read and understood\r\n- [ ] A tight loop command exists and has been run at least once\r\n- [ ] Loop is red-capable: it asserts the user's exact symptom, not a nearby failure\r\n- [ ] Loop is deterministic, or a flaky bug has a high enough reproduction rate to debug\r\n- [ ] Recent changes identified and reviewed\r\n- [ ] Evidence gathered (logs, state, data flow)\r\n- [ ] Problem isolated to specific component\u002Fcode\r\n- [ ] Root cause hypotheses can be stated and tested\r\n\r\n**STOP:** Do not proceed to Phase 2 until you understand WHY it's happening.\r\n\r\n---\r\n\r\n## Phase 2: Pattern Analysis\r\n\r\n**Find the pattern before fixing:**\r\n\r\n### 0. Minimize the Reproduction\r\n\r\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.\r\n\r\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.\r\n\r\n### 1. Find Working Examples\r\n\r\n- Locate similar working code in the same codebase\r\n- What works that's similar to what's broken?\r\n\r\n**Action:** Use `search_files` to find comparable patterns:\r\n\r\n```python\r\nsearch_files(\"similar_pattern\", path=\"src\u002F\", file_glob=\"*.py\")\r\n```\r\n\r\n### 2. Compare Against References\r\n\r\n- If implementing a pattern, read the reference implementation COMPLETELY\r\n- Don't skim — read every line\r\n- Understand the pattern fully before applying\r\n\r\n### 3. Identify Differences\r\n\r\n- What's different between working and broken?\r\n- List every difference, however small\r\n- Don't assume \"that can't matter\"\r\n\r\n### 4. Understand Dependencies\r\n\r\n- What other components does this need?\r\n- What settings, config, environment?\r\n- What assumptions does it make?\r\n\r\n---\r\n\r\n## Phase 3: Hypothesis and Testing\r\n\r\n**Scientific method:**\r\n\r\n### 1. Form Ranked Falsifiable Hypotheses\r\n\r\n- Generate 3–5 plausible hypotheses before testing any single one.\r\n- Rank them by likelihood and cheapness to falsify.\r\n- State the prediction each hypothesis makes: \"If X is the cause, then changing or observing Y should make Z happen.\"\r\n- Discard or sharpen any hypothesis that does not make a testable prediction.\r\n\r\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.\r\n\r\n### 2. Test Minimally\r\n\r\n- Test the highest-ranked hypothesis with the smallest possible probe.\r\n- Change one variable at a time.\r\n- Don't fix multiple things at once.\r\n- Prefer debugger\u002FREPL inspection when available; one breakpoint beats ten logs.\r\n- If you add logs, tag every temporary line with a unique prefix such as `[DEBUG-a4f2]` so cleanup is a single search.\r\n\r\n### 3. Verify Before Continuing\r\n\r\n- Did it work? → Phase 4\r\n- Didn't work? → Form NEW hypothesis\r\n- DON'T add more fixes on top\r\n\r\n### 4. When You Don't Know\r\n\r\n- Say \"I don't understand X\"\r\n- Don't pretend to know\r\n- Ask the user for help\r\n- Research more\r\n\r\n---\r\n\r\n## Phase 4: Implementation\r\n\r\n**Fix the root cause, not the symptom:**\r\n\r\n### 1. Create Failing Test Case\r\n\r\n- Simplest possible reproduction\r\n- Automated test if possible\r\n- MUST have before fixing\r\n- Use the `test-driven-development` skill\r\n\r\n### 2. Implement Single Fix\r\n\r\n- Address the root cause identified\r\n- ONE change at a time\r\n- No \"while I'm here\" improvements\r\n- No bundled refactoring\r\n\r\n### 3. Verify Fix\r\n\r\n```bash\r\n# Run the specific regression test\r\npytest tests\u002Ftest_module.py::test_regression -v\r\n\r\n# Run full suite — no regressions\r\npytest tests\u002F -q\r\n```\r\n\r\n### 4. If Fix Doesn't Work — The Rule of Three\r\n\r\n- **STOP.**\r\n- Count: How many fixes have you tried?\r\n- If \u003C 3: Return to Phase 1, re-analyze with new information\r\n- **If ≥ 3: STOP and question the architecture (step 5 below)**\r\n- DON'T attempt Fix #4 without architectural discussion\r\n\r\n### 5. If 3+ Fixes Failed: Question Architecture\r\n\r\n**Pattern indicating an architectural problem:**\r\n- Each fix reveals new shared state\u002Fcoupling in a different place\r\n- Fixes require \"massive refactoring\" to implement\r\n- Each fix creates new symptoms elsewhere\r\n\r\n**STOP and question fundamentals:**\r\n- Is this pattern fundamentally sound?\r\n- Are we \"sticking with it through sheer inertia\"?\r\n- Should we refactor the architecture vs. continue fixing symptoms?\r\n\r\n**Discuss with the user before attempting more fixes.**\r\n\r\nThis is NOT a failed hypothesis — this is a wrong architecture.\r\n\r\n---\r\n\r\n## Red Flags — STOP and Follow Process\r\n\r\nIf you catch yourself thinking:\r\n- \"Quick fix for now, investigate later\"\r\n- \"Just try changing X and see if it works\"\r\n- \"Add multiple changes, run tests\"\r\n- \"Skip the test, I'll manually verify\"\r\n- \"It's probably X, let me fix that\"\r\n- \"I don't fully understand but this might work\"\r\n- \"Pattern says X but I'll adapt it differently\"\r\n- \"Here are the main problems: [lists fixes without investigation]\"\r\n- Proposing solutions before tracing data flow\r\n- **\"One more fix attempt\" (when already tried 2+)**\r\n- **Each fix reveals a new problem in a different place**\r\n\r\n**ALL of these mean: STOP. Return to Phase 1.**\r\n\r\n**If 3+ fixes failed:** Question the architecture (Phase 4 step 5).\r\n\r\n## Common Rationalizations\r\n\r\n| Excuse | Reality |\r\n|--------|---------|\r\n| \"Issue is simple, don't need process\" | Simple issues have root causes too. Process is fast for simple bugs. |\r\n| \"Emergency, no time for process\" | Systematic debugging is FASTER than guess-and-check thrashing. |\r\n| \"Just try this first, then investigate\" | First fix sets the pattern. Do it right from the start. |\r\n| \"I'll write test after confirming fix works\" | Untested fixes don't stick. Test first proves it. |\r\n| \"Multiple fixes at once saves time\" | Can't isolate what worked. Causes new bugs. |\r\n| \"Reference too long, I'll adapt the pattern\" | Partial understanding guarantees bugs. Read it completely. |\r\n| \"I see the problem, let me fix it\" | Seeing symptoms ≠ understanding root cause. |\r\n| \"One more fix attempt\" (after 2+ failures) | 3+ failures = architectural problem. Question the pattern, don't fix again. |\r\n\r\n## Quick Reference\r\n\r\n| Phase | Key Activities | Success Criteria |\r\n|-------|---------------|------------------|\r\n| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence, trace data flow | Understand WHAT and WHY |\r\n| **2. Pattern** | Find working examples, compare, identify differences | Know what's different |\r\n| **3. Hypothesis** | Form theory, test minimally, one variable at a time | Confirmed or new hypothesis |\r\n| **4. Implementation** | Create regression test, fix root cause, verify | Bug resolved, all tests pass |\r\n\r\n## Hermes Agent Integration\r\n\r\n### Investigation Tools\r\n\r\nUse these Hermes tools during Phase 1:\r\n\r\n- **`search_files`** — Find error strings, trace function calls, locate patterns\r\n- **`read_file`** — Read source code with line numbers for precise analysis\r\n- **`terminal`** — Run tests, check git history, reproduce bugs\r\n- **`web_search`\u002F`web_extract`** — Research error messages, library docs\r\n\r\n### With delegate_task\r\n\r\nFor complex multi-component debugging, dispatch investigation subagents:\r\n\r\n```python\r\ndelegate_task(\r\n    goal=\"Investigate why [specific test\u002Fbehavior] fails\",\r\n    context=\"\"\"\r\n    Follow systematic-debugging skill:\r\n    1. Read the error message carefully\r\n    2. Reproduce the issue\r\n    3. Trace the data flow to find root cause\r\n    4. Report findings — do NOT fix yet\r\n\r\n    Error: [paste full error]\r\n    File: [path to failing code]\r\n    Test command: [exact command]\r\n    \"\"\",\r\n    toolsets=['terminal', 'file']\r\n)\r\n```\r\n\r\n### With test-driven-development\r\n\r\nWhen fixing bugs:\r\n1. Write a test that reproduces the bug (RED)\r\n2. Debug systematically to find root cause\r\n3. Fix the root cause (GREEN)\r\n4. The test proves the fix and prevents regression\r\n\r\n## Real-World Impact\r\n\r\nFrom debugging sessions:\r\n- Systematic approach: 15-30 minutes to fix\r\n- Random fixes approach: 2-3 hours of thrashing\r\n- First-time fix rate: 95% vs 40%\r\n- New bugs introduced: Near zero vs common\r\n\r\n**No shortcuts. No guessing. Systematic always wins.**\r\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":37,"description":7},"Hermes Agent (adapted from obra\u002Fsuperpowers)","1.1.0",{"hermes":27},{"tags":28,"related_skills":34},[29,30,31,32,33],"debugging","troubleshooting","problem-solving","root-cause","investigation",[35,36],"test-driven-development","subagent-driven-development",[38,39,40],"linux","macos","windows","main","a3f3199bb87ec3c91248f68a39d88527e1847ae9","skills\u002Fsoftware-development\u002Fsystematic-debugging","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content","https:\u002F\u002Fgithub.com\u002Fchaorenex1","https:\u002F\u002Fblog.aduib.com","A programmer whose only hobby in life is coding","2026-10-20 00:34:32",{"source":8,"skillName":5,"commands":50,"prompt":60,"zipAvailable":61},[51,54,57],{"tool":52,"command":53},"npx","npx skills add chaorenex1\u002Fhermes-home-content --skill systematic-debugging",{"tool":55,"command":56},"bunx","bunx skills add chaorenex1\u002Fhermes-home-content --skill systematic-debugging",{"tool":58,"command":59},"pnpm","pnpm dlx skills add chaorenex1\u002Fhermes-home-content --skill systematic-debugging","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",true,[],[64,71,78,85,92,99],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M7F8GF32YD5MBQW2TGSRH1YP","web-retrieval-resilience","Web tools fail or search rules break: repair or fall back.","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fweb\u002Fweb-retrieval-resilience\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M7F8FP46QESQMCZ1KBT3TW3R","blocked-page-recovery","Use when a fetch fails: 403\u002F429, paywall, WAF, bot wall.","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fweb\u002Fblocked-page-recovery\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M7F8ER6VXHBNVRQBZS7X08SE","verification-loop","Run a six-phase verification of a Claude Code session's work — build, type check, lint, tests with coverage, security grep, and diff review — then produce a PASS\u002FFAIL verification report. Use when verifying work after completing a feature or refactor, before creating a PR, or when quality gates must pass.","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Fverification-loop\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7F8E4BQJ38KVQVM3MT20PYV","unreal-world-builder","开放世界与环境专家——精通 UE5 World Partition、Landscape、程序化植被、HLOD 和大规模关卡流式加载，打造无缝开放世界体验","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Funreal-engine\u002Funreal-world-builder\u002FSKILL.md",[],[],{"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":98,"publishedAt":19},"01M7F8D747SQW2FTP7GBSX38BR","unreal-technical-artist","Unreal Engine 视觉管线专家——精通材质编辑器、Niagara 特效、程序化内容生成和 UE5 项目的美术到引擎管线","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Funreal-engine\u002Funreal-technical-artist\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M7F8CKHYJVZVBTN0321J88T2","unreal-systems-engineer","性能与混合架构专家——精通 C++\u002FBlueprint 边界、Nanite 几何体、Lumen GI 和 Gameplay Ability System，面向 AAA 级 Unreal Engine 项目","https:\u002F\u002Fgithub.com\u002Fchaorenex1\u002Fhermes-home-content\u002Fblob\u002Fmain\u002Fskills\u002Funreal-engine\u002Funreal-systems-engineer\u002FSKILL.md",[],[]]