[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CY4P2PBJ7ASED99PSQXJ98":3,"skill-same:01M6CY4P2PBJ7ASED99PSQXJ98":50},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":24,"linkOnly":25,"markdownContent":26,"markdownBody":27,"frontMatter":28,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":13,"repositoryHtmlUrl":33,"repositoryHomepageUrl":6,"ownerHtmlUrl":34,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":35,"install":36,"resources":49},"01M6CY4P2PBJ7ASED99PSQXJ98","systematic-debugging",null,"Use when debugging unexpected errors during implementation -- provides a structured 4-phase methodology instead of trial-and-error","The-Rabak\u002Fcompound-engineering-plugin","The-Rabak","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F44833742?v=4","01M6CY211HB58Y8JNWWEV9FGN1","01M6CY2165MYWKS66VN01X82EB",1,"MIT","https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin\u002Fblob\u002Fmain\u002Fplugins\u002Fcompound-engineering\u002Fskills\u002Fsystematic-debugging\u002FSKILL.md",[],[18,19,20,21,22,23],"systematic debugging","debugging","methodology","use","implementation","structured","2026-11-10 10:12:30",false,"---\nname: systematic-debugging\ndescription: Use when debugging unexpected errors during implementation -- provides a structured 4-phase methodology instead of trial-and-error\nmodel: claude-sonnet-5\n---\n\n# Systematic Debugging\n\nA structured methodology for debugging unexpected errors encountered during implementation. Prevents trial-and-error guessing by enforcing a disciplined observe-hypothesize-test-fix cycle with an explicit causal-chain gate.\n\n**Announce at start:** \"I'm using the systematic-debugging skill to diagnose this issue.\"\n\n## When to Use\n\n- A test fails unexpectedly during implementation\n- An error occurs that you did not anticipate\n- A subagent has retried 2+ times without success\n- Something \"should work\" but does not\n- You are tempted to make random changes hoping something fixes it\n\n## When NOT to Use\n\n- The error message is clear and the fix is obvious (just fix it)\n- You are validating a reported bug (use the `bug-reproduction-validator` agent instead)\n- The failure is a known issue documented in `docs\u002Fsolutions\u002F`\n\n## The 4-Phase Process\n\n### Phase 1: Observe\n\nGather evidence before forming any theories. Do not skip this phase.\n\n1. **Reproduce the error** -- Run the exact command that failed. Confirm you see the same error.\n2. **Read the full error** -- Read the COMPLETE error message, stack trace, and any surrounding output. Do not skim.\n3. **Check the context** -- What changed recently? What was the last thing that worked? What is different now?\n4. **Gather state** -- Check relevant logs, database state, environment variables, configuration files, or any other state that could be relevant.\n5. **Note the symptoms** -- Write down exactly what you observe:\n   - What happens (the error)\n   - What should happen (expected behavior)\n   - When it happens (always, sometimes, under specific conditions)\n6. **Define the boundary** -- Identify the failing surface precisely:\n   - entry point\n   - affected module or feature home\n   - dependencies involved\n   - whether this looks local, environmental, or cross-boundary\n7. **Record prior attempts** -- What fixes or hypotheses were already tried? Which ones failed?\n\n**Output of Phase 1:** A clear, factual description of the symptoms with no theories attached.\n\n### Phase 2: Hypothesize\n\nForm structured theories about the root cause. Do not jump to fixing yet.\n\n1. **List 3 possible root causes** ranked by likelihood.\n\n2. **For each hypothesis, write the causal chain explicitly:**\n\n   ```text\n   Trigger -> Mechanism -> Failure\n   ```\n\n   Example:\n\n   ```text\n   Empty cache key -> config loader returns fallback shape -> validator receives missing field -> request fails with 500\n   ```\n\n3. **Identify the uncertain links** in each chain.\n\n4. **For each hypothesis, define:**\n   - What evidence would confirm it\n   - What evidence would rule it out\n   - One prediction the system should make if the hypothesis is true\n   - How to test that prediction without implementing the fix yet\n\n5. **Run a lightweight assumption audit:**\n   - Which inputs am I assuming are valid?\n   - Which environment facts am I assuming are true?\n   - Which \"this should never happen\" beliefs need verification?\n\n**Do NOT:**\n- Start fixing before completing this phase\n- Settle on one theory without considering alternatives\n- Assume the most obvious cause is correct without verification\n- Proceed without at least one explicit trigger -> mechanism -> failure chain\n\n### Phase 3: Test\n\nVerify or eliminate each hypothesis systematically. Start with the most likely.\n\n1. **Test the most likely hypothesis first:**\n   - Add a diagnostic check (log statement, assertion, breakpoint, print)\n   - Run the failing scenario\n   - Does the evidence confirm or rule out this hypothesis?\n\n2. **If confirmed:** Move to Phase 4 (Fix)\n3. **If ruled out:** Test the next hypothesis\n4. **If all 3 ruled out:** Return to Phase 2 with new hypotheses based on what you learned\n\nFor every uncertain link in the causal chain, test a prediction:\n\n- \"If the config is malformed before validation, the raw config dump should already be missing field X\"\n- \"If the queue worker is using stale code, restarting it should change the stack frame path\"\n- \"If the issue is permission-based, the same request should succeed under the admin fixture\"\n\n**Techniques:**\n- **Binary search:** Comment out half the changes, see if the error persists. Narrow down.\n- **Isolation:** Run the failing code in isolation (unit test, REPL, minimal reproduction)\n- **Comparison:** Compare working state (git stash, previous commit) with broken state\n- **Minimal reproduction:** Create the smallest possible case that reproduces the error\n\n**Do NOT:**\n- Make changes to fix the problem while still in this phase\n- Skip hypotheses because you \"feel\" the first one is right\n- Change multiple things at once (change one variable at a time)\n- Keep trusting a hypothesis after a failed fix or failed prediction. Invalidate it and loop back explicitly.\n\n### Phase 4: Fix\n\nApply a targeted fix to the confirmed root cause. You are only allowed to enter this phase once the causal chain is explicit enough to explain why the failure happens.\n\n1. **Fix the root cause** -- not the symptom. If the error is \"undefined is not a function,\" the fix is not adding a null check -- it is understanding WHY the value is undefined and fixing THAT.\n\n2. **Make the minimal fix** -- Change as little as possible. Do not refactor, clean up, or \"improve\" other code while fixing the bug.\n\n3. **Verify the fix:**\n   - Run the exact same command\u002Ftest that originally failed\n   - Confirm it passes\n   - Run related tests to check you did not break anything else\n   - If the fix introduces new failures, return to Phase 1 with the new error\n\n4. **Check for siblings** -- Is this same bug likely to exist in similar code elsewhere? If so, fix those too.\n\n5. **Remove diagnostics** -- Remove any log statements, debug prints, or breakpoints added during Phase 3.\n\n6. **Invalidate failed fixes explicitly** -- If the attempted fix does not hold, say what part of the chain was wrong and return to Phase 1 or 2. Never silently stack another guess on top.\n\n### Design Escalation Gate\n\nStop treating the problem as a local bug and recommend a design-level workflow when any of these are true:\n\n- the real fix changes feature-home ownership or shared\u002Fglobal boundaries\n- the failure exposes a wrong abstraction, wrong contract, or missing seam\n- multiple attempted local fixes fail because the architecture assumption is wrong\n- the smallest honest fix is no longer small\n\nWhen that happens, recommend `\u002Fworkflows:debug` for orchestration or escalate to `\u002Fworkflows:brainstorm`, `\u002Fworkflows:architecture`, or `\u002Fdeepen-plan` as appropriate.\n\n## After Debugging\n\n### Document the Root Cause\n\nInclude in your execution report:\n\n```markdown\n### Debugging Session\n- **Symptom:** [what failed]\n- **Causal chain:** [trigger -> mechanism -> failure]\n- **Root cause:** [what was actually wrong]\n- **Fix:** [what was changed]\n- **Prevention:** [how to prevent this in the future]\n```\n\nThis information feeds into the learnings brief for subsequent tasks and can be captured in `docs\u002Fsolutions\u002F` via `\u002Fworkflows:compound`.\n\n### Feed Forward\n\nIf you discovered a pattern that would help prevent this issue in the future:\n- Note it in the \"Patterns Discovered\" section of your execution report\n- The orchestrator will add it to the learnings brief for subsequent tasks\n\n## Anti-Patterns (What NOT to Do)\n\n- **Shotgun debugging:** Making random changes hoping something works. Always hypothesize first.\n- **Fix-and-pray:** Applying a fix without understanding why it works. If you cannot explain the root cause, you have not found it.\n- **Stack Overflow driven development:** Copying a fix from the internet without understanding what it does or why it applies to your situation.\n- **Symptom masking:** Adding a try\u002Fcatch, null check, or default value that hides the real problem instead of fixing it.\n- **Tunnel vision:** Fixating on one hypothesis without considering alternatives. The first theory is often wrong.\n- **Chainless fixing:** Changing code before you can state the trigger -> mechanism -> failure path with reasonable confidence.\n","# Systematic Debugging\n\nA structured methodology for debugging unexpected errors encountered during implementation. Prevents trial-and-error guessing by enforcing a disciplined observe-hypothesize-test-fix cycle with an explicit causal-chain gate.\n\n**Announce at start:** \"I'm using the systematic-debugging skill to diagnose this issue.\"\n\n## When to Use\n\n- A test fails unexpectedly during implementation\n- An error occurs that you did not anticipate\n- A subagent has retried 2+ times without success\n- Something \"should work\" but does not\n- You are tempted to make random changes hoping something fixes it\n\n## When NOT to Use\n\n- The error message is clear and the fix is obvious (just fix it)\n- You are validating a reported bug (use the `bug-reproduction-validator` agent instead)\n- The failure is a known issue documented in `docs\u002Fsolutions\u002F`\n\n## The 4-Phase Process\n\n### Phase 1: Observe\n\nGather evidence before forming any theories. Do not skip this phase.\n\n1. **Reproduce the error** -- Run the exact command that failed. Confirm you see the same error.\n2. **Read the full error** -- Read the COMPLETE error message, stack trace, and any surrounding output. Do not skim.\n3. **Check the context** -- What changed recently? What was the last thing that worked? What is different now?\n4. **Gather state** -- Check relevant logs, database state, environment variables, configuration files, or any other state that could be relevant.\n5. **Note the symptoms** -- Write down exactly what you observe:\n   - What happens (the error)\n   - What should happen (expected behavior)\n   - When it happens (always, sometimes, under specific conditions)\n6. **Define the boundary** -- Identify the failing surface precisely:\n   - entry point\n   - affected module or feature home\n   - dependencies involved\n   - whether this looks local, environmental, or cross-boundary\n7. **Record prior attempts** -- What fixes or hypotheses were already tried? Which ones failed?\n\n**Output of Phase 1:** A clear, factual description of the symptoms with no theories attached.\n\n### Phase 2: Hypothesize\n\nForm structured theories about the root cause. Do not jump to fixing yet.\n\n1. **List 3 possible root causes** ranked by likelihood.\n\n2. **For each hypothesis, write the causal chain explicitly:**\n\n   ```text\n   Trigger -> Mechanism -> Failure\n   ```\n\n   Example:\n\n   ```text\n   Empty cache key -> config loader returns fallback shape -> validator receives missing field -> request fails with 500\n   ```\n\n3. **Identify the uncertain links** in each chain.\n\n4. **For each hypothesis, define:**\n   - What evidence would confirm it\n   - What evidence would rule it out\n   - One prediction the system should make if the hypothesis is true\n   - How to test that prediction without implementing the fix yet\n\n5. **Run a lightweight assumption audit:**\n   - Which inputs am I assuming are valid?\n   - Which environment facts am I assuming are true?\n   - Which \"this should never happen\" beliefs need verification?\n\n**Do NOT:**\n- Start fixing before completing this phase\n- Settle on one theory without considering alternatives\n- Assume the most obvious cause is correct without verification\n- Proceed without at least one explicit trigger -> mechanism -> failure chain\n\n### Phase 3: Test\n\nVerify or eliminate each hypothesis systematically. Start with the most likely.\n\n1. **Test the most likely hypothesis first:**\n   - Add a diagnostic check (log statement, assertion, breakpoint, print)\n   - Run the failing scenario\n   - Does the evidence confirm or rule out this hypothesis?\n\n2. **If confirmed:** Move to Phase 4 (Fix)\n3. **If ruled out:** Test the next hypothesis\n4. **If all 3 ruled out:** Return to Phase 2 with new hypotheses based on what you learned\n\nFor every uncertain link in the causal chain, test a prediction:\n\n- \"If the config is malformed before validation, the raw config dump should already be missing field X\"\n- \"If the queue worker is using stale code, restarting it should change the stack frame path\"\n- \"If the issue is permission-based, the same request should succeed under the admin fixture\"\n\n**Techniques:**\n- **Binary search:** Comment out half the changes, see if the error persists. Narrow down.\n- **Isolation:** Run the failing code in isolation (unit test, REPL, minimal reproduction)\n- **Comparison:** Compare working state (git stash, previous commit) with broken state\n- **Minimal reproduction:** Create the smallest possible case that reproduces the error\n\n**Do NOT:**\n- Make changes to fix the problem while still in this phase\n- Skip hypotheses because you \"feel\" the first one is right\n- Change multiple things at once (change one variable at a time)\n- Keep trusting a hypothesis after a failed fix or failed prediction. Invalidate it and loop back explicitly.\n\n### Phase 4: Fix\n\nApply a targeted fix to the confirmed root cause. You are only allowed to enter this phase once the causal chain is explicit enough to explain why the failure happens.\n\n1. **Fix the root cause** -- not the symptom. If the error is \"undefined is not a function,\" the fix is not adding a null check -- it is understanding WHY the value is undefined and fixing THAT.\n\n2. **Make the minimal fix** -- Change as little as possible. Do not refactor, clean up, or \"improve\" other code while fixing the bug.\n\n3. **Verify the fix:**\n   - Run the exact same command\u002Ftest that originally failed\n   - Confirm it passes\n   - Run related tests to check you did not break anything else\n   - If the fix introduces new failures, return to Phase 1 with the new error\n\n4. **Check for siblings** -- Is this same bug likely to exist in similar code elsewhere? If so, fix those too.\n\n5. **Remove diagnostics** -- Remove any log statements, debug prints, or breakpoints added during Phase 3.\n\n6. **Invalidate failed fixes explicitly** -- If the attempted fix does not hold, say what part of the chain was wrong and return to Phase 1 or 2. Never silently stack another guess on top.\n\n### Design Escalation Gate\n\nStop treating the problem as a local bug and recommend a design-level workflow when any of these are true:\n\n- the real fix changes feature-home ownership or shared\u002Fglobal boundaries\n- the failure exposes a wrong abstraction, wrong contract, or missing seam\n- multiple attempted local fixes fail because the architecture assumption is wrong\n- the smallest honest fix is no longer small\n\nWhen that happens, recommend `\u002Fworkflows:debug` for orchestration or escalate to `\u002Fworkflows:brainstorm`, `\u002Fworkflows:architecture`, or `\u002Fdeepen-plan` as appropriate.\n\n## After Debugging\n\n### Document the Root Cause\n\nInclude in your execution report:\n\n```markdown\n### Debugging Session\n- **Symptom:** [what failed]\n- **Causal chain:** [trigger -> mechanism -> failure]\n- **Root cause:** [what was actually wrong]\n- **Fix:** [what was changed]\n- **Prevention:** [how to prevent this in the future]\n```\n\nThis information feeds into the learnings brief for subsequent tasks and can be captured in `docs\u002Fsolutions\u002F` via `\u002Fworkflows:compound`.\n\n### Feed Forward\n\nIf you discovered a pattern that would help prevent this issue in the future:\n- Note it in the \"Patterns Discovered\" section of your execution report\n- The orchestrator will add it to the learnings brief for subsequent tasks\n\n## Anti-Patterns (What NOT to Do)\n\n- **Shotgun debugging:** Making random changes hoping something works. Always hypothesize first.\n- **Fix-and-pray:** Applying a fix without understanding why it works. If you cannot explain the root cause, you have not found it.\n- **Stack Overflow driven development:** Copying a fix from the internet without understanding what it does or why it applies to your situation.\n- **Symptom masking:** Adding a try\u002Fcatch, null check, or default value that hides the real problem instead of fixing it.\n- **Tunnel vision:** Fixating on one hypothesis without considering alternatives. The first theory is often wrong.\n- **Chainless fixing:** Changing code before you can state the trigger -> mechanism -> failure path with reasonable confidence.\n",{"name":5,"model":29,"description":7},"claude-sonnet-5","main","4c70ff7e10e692dfcc6d7877a6e57dd08df94d9b","plugins\u002Fcompound-engineering\u002Fskills\u002Fsystematic-debugging","https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin","https:\u002F\u002Fgithub.com\u002FThe-Rabak","2026-07-28 15:25:35",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add The-Rabak\u002Fcompound-engineering-plugin --skill systematic-debugging",{"tool":42,"command":43},"bunx","bunx skills add The-Rabak\u002Fcompound-engineering-plugin --skill systematic-debugging",{"tool":45,"command":46},"pnpm","pnpm dlx skills add The-Rabak\u002Fcompound-engineering-plugin --skill systematic-debugging","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin\u002Fblob\u002Fmain\u002Fplugins\u002Fcompound-engineering\u002Fskills\u002Fsystematic-debugging\u002FSKILL.md",true,[],[51,68,77,87,95,102],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":62,"publishedAt":24},"01M6CY858Z5RCC30TKAVBDJ6SZ","skill-one","Shared reusable skill.","https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fsample-portable-plugin\u002Fskills\u002Fskill-one\u002FSKILL.md",[57],{"categoryNo":58,"categoryName":59,"taxonomyType":60,"taxonomyTypeDesc":61},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[63,64,65,66,67],"skill one","shared","reusable","haiku","gpt",{"skillNo":69,"name":53,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":74,"publishedAt":24},"01M6CY843KQG3FQF6259420CCD","Sample skill","https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fsample-plugin\u002Fskills\u002Fskill-one\u002FSKILL.md",[73],{"categoryNo":58,"categoryName":59,"taxonomyType":60,"taxonomyTypeDesc":61},[63,75,76],"sample","sample skill",{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":84,"publishedAt":24},"01M6CY82607GGPWR5H25SY74H2","disabled-skill","A skill with model invocation disabled","https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fsample-plugin\u002Fskills\u002Fdisabled-skill\u002FSKILL.md",[83],{"categoryNo":58,"categoryName":59,"taxonomyType":60,"taxonomyTypeDesc":61},[85,86],"disabled skill","model",{"skillNo":88,"name":89,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":24},"01M6CY80RWMK81T97A2Q5KAFAF","default-skill","https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fcustom-paths\u002Fskills\u002Fdefault-skill\u002FSKILL.md",[],[93,94],"default skill","default",{"skillNo":96,"name":97,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":24},"01M6CY7ZK2PMV75ES90W6YYD4S","custom-skill","https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fcustom-paths\u002Fcustom-skills\u002Fcustom-skill\u002FSKILL.md",[],[101],"custom skill",{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":109,"publishedAt":24},"01M6CY7V6C7HFCNJEVNFT1X00T","workflow-next-step","This skill should be used at the end of core compound-engineering workflows to inspect completed artifacts, show the workflow progress checklist, and give the exact next-session command with inputs.","https:\u002F\u002Fgithub.com\u002FThe-Rabak\u002Fcompound-engineering-plugin\u002Fblob\u002Fmain\u002Fportable\u002Fcompound-engineering\u002Fskills\u002Fworkflow-next-step\u002FSKILL.md",[108],{"categoryNo":58,"categoryName":59,"taxonomyType":60,"taxonomyTypeDesc":61},[110,111,112,113,114,115,116,117,118,119,120,121],"workflow","next","workflow next step","compound","show","checklist","session","command","engineering","artifacts","core","workflows"]