[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72TA9K2M2G9B02SW8YWSGFJ":3,"skill-same:01M72TA9K2M2G9B02SW8YWSGFJ":87},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M72TA9K2M2G9B02SW8YWSGFJ","ywc-debug-rootcause",null,"(ywc) Use when a bug, test\u002Fbuild failure, or other unexpected behavior appears before any fix is proposed. Forces root-cause investigation and blocks symptom patching. Triggers: \"디버그\", \"버그\", \"debug\", \"デバッグ\", \"ywc-debug-rootcause\". Do not use for implementation drafting (use ywc-code-gen), incident postmortems (use ywc-incident-postmortem), security triage (use ywc-security-audit), or pre-implementation confidence checks (use ywc-confidence-gate).","yongwoon\u002Fywc-agent-toolkit","yongwoon","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F9317029?v=4","01M72SZSF6VKANKG5QTMV4V95S","01M72SZSG8HHC3W2CV5P7EJ5AH",8,"MIT","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: ywc-debug-rootcause\ndescription: >-\n  (ywc) Use when a bug, test\u002Fbuild failure, or other unexpected behavior\n  appears before any fix is proposed. Forces root-cause investigation and\n  blocks symptom patching. Triggers: \"디버그\", \"버그\", \"debug\", \"デバッグ\",\n  \"ywc-debug-rootcause\". Do not use for implementation drafting (use\n  ywc-code-gen), incident postmortems (use ywc-incident-postmortem), security\n  triage (use ywc-security-audit), or pre-implementation confidence checks\n  (use ywc-confidence-gate).\n---\n\n# ywc-debug-rootcause\n\n**Announce at start:** \"I'm using the ywc-debug-rootcause skill to identify root cause through 4-phase investigation before any fix is proposed.\"\n\nThis skill enforces the discipline of finding the **why** before touching the **what**. It exists because guess-and-fix loops produce three failure modes that ywc workflows must avoid: (1) symptom fixes that mask the real defect and surface elsewhere later; (2) compounding edits that make the next investigation harder; (3) \"architecture wrong\" cases mistaken for \"fix harder\" cases, wasting 3–10× the rework. Adapted from `superpowers:systematic-debugging`.\n\n## The Iron Law\n\n```text\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\n```\n\nIf Phase 1 has not been completed, fixes cannot be proposed. \"Try X and see\" is a guess, not an investigation.\n\n## Rationalization Defense\n\nWhen tempted to skip a phase, check this table first:\n\n| Excuse | Reality |\n|---|---|\n| \"I see the problem, let me just fix it\" | Seeing a *symptom* is not understanding the *cause*. The first reproducible defect-on-line-X is almost always a downstream effect of an upstream bad value. Trace the data flow at least one hop upstream before editing. |\n| \"Emergency, no time for the 4 phases\" | The 4 phases take 15–30 minutes for a typical bug; guess-and-check takes 2–3 hours of thrashing with a 40% first-time-fix rate. Pressure makes the systematic path **faster**, not slower. |\n| \"I'll try one quick fix, then investigate if it doesn't work\" | The first fix sets the pattern for the session. After the first symptom-fix, every subsequent attempt becomes \"fix something else\", not \"investigate\". Do the investigation first. |\n| \"I've already tried 3 fixes, one more should do it\" | Three failed fixes require the architecture-suspicion gate (Phase 4 §5). Stop by default; one fourth attempt requires both separate evidence-linked debug-mode analyst fields. A failed fourth attempt ends the loop. |\n| \"Test fails locally, I'll skip Phase 2 (pattern analysis) since I know the code\" | Familiarity is the failure mode. The \"I know this code\" agent skips reading the *working* sibling implementation and reinvents a bug the sibling already solved. Always read a working reference end-to-end before fixing the broken one. |\n| \"Logging at boundaries is overkill, I'll just read the source\" | Multi-component systems (CI → build → sign; API → service → DB; controller → middleware → handler) fail at boundaries, not inside components. Source-reading without boundary logging produces false hypotheses about which component is at fault. |\n| \"Symptom is intermittent, must be flakiness\" | \"Flakiness\" is the label agents give to bugs they did not investigate. ≥95% of \"flaky test\" diagnoses turn out to be reproducible race conditions or environment leaks once instrumented. Skip the flakiness label and investigate. |\n| \"I'll fix this AND clean up the surrounding code while I'm here\" | Bundled changes mean you cannot tell which change fixed the bug, and the cleanup may *cause* a new bug. One investigation → one fix → one verification. Refactor in a separate session. |\n\n**Violating the letter of these rules is violating the spirit.** The 4 phases exist because each one catches a class of failure the others miss.\n\n## When to Use\n\nUse for **any** technical defect, including:\n\n- Test failure (unit, integration, E2E)\n- Production bug\n- Build failure \u002F compilation error\n- Type-check error that resists obvious fix\n- Performance regression\n- Integration \u002F cross-component failure\n- Unexpected behavior in code that \"used to work\"\n\nUse this **especially** when:\n\n- Under time pressure (the temptation to guess peaks here)\n- A previous fix attempt did not work\n- The symptom is intermittent or environment-dependent\n- \"Just one quick fix\" feels obvious\n\nDo **not** skip when:\n\n- The bug looks \"simple\" — simple bugs have causes too\n- The user is impatient — systematic is still faster than thrashing\n- You are tired — exhaustion is not a justification\n\n## Analyst contract\n\nEvery analyst packet carries `Caller: ywc-debug-rootcause` and `analysis_mode=debug_hypotheses` plus bounded evidence. Missing, unknown, or mismatched caller\u002Fmode returns `NEEDS_CONTEXT` without inferring another mode. Validate the returned Status\u002FSummary\u002FFinding counts envelope and matching Analysis mode before consuming advice; owner\u002Finput\u002Foutput\u002Fstatus mismatch returns `NEEDS_CONTEXT`. An analyst refusal consumes the existing dispatch budget; preserve the caller's original gate and surface the missing evidence instead of re-dispatching or falling through. The analyst returns inline advice and never writes the caller's report or runs probes. Unavailable delegation uses the documented inline path; unavailable live runtime evidence is `UNVERIFIED — instruction contract only`.\n\n## The Four Phases\n\nComplete each phase before proceeding to the next.\n\n### Phase 1: Root-Cause Investigation\n\nBefore proposing **any** fix:\n\n0. **Establish the smallest feedback loop first.** Use a focused test, build check, script or bounded manual reproduction. Record `Feedback loop`, `Catches`, `Misses`, and the observed failure before any fix. If automated reproduction is unavailable, record manual evidence and constraints; do not fabricate RED or claim execution PASS. Read-only analyst advice is not a reproduced failure.\n1. **Read error messages carefully.** Read the full stack trace, every line. Note file paths, line numbers, error codes. Errors often contain the exact name of the missing thing.\n2. **Reproduce consistently.** Run the minimal feedback loop until its result is predictable. If reproduction is unavailable, retain the manual evidence and constraints from step 0, gather the missing data and do not propose a speculative fix.\n3. **Check recent changes.** Run `git log --oneline -20`, `git diff HEAD~1`, check dependency bumps, environment changes, config changes since the last known-good state.\n4. **Add diagnostic instrumentation at component boundaries.** For multi-component systems, the failure is almost always at a boundary, not inside a component. Log what each component receives and what it emits. Run once to gather evidence. **Read the evidence before forming a hypothesis.**\n5. **Trace data flow upstream.** Where does the bad value originate? What called the failing function with that value? Keep tracing until the *origin* is found; fix at the origin, not at the symptom.\n\nPhase 1 exit condition: you can answer in one sentence **what** is wrong and **why** it is happening. If either answer is fuzzy, continue Phase 1.\n\nWhen local evidence cannot produce a confident initial hypothesis and the current Codex session has an available subagent\u002Fdelegation tool, request at most one independent `ywc-root-cause-analyst` pass. Send `Caller: ywc-debug-rootcause`, `analysis_mode=debug_hypotheses`, and only a bounded packet: failure symptom, timeline, stack trace or logs, recent diff, rejected hypotheses, relevant code snippet, and current candidate cause. Ask for `Status: \u003CDONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT>` plus ranked, falsifiable hypotheses (3–5 when evidence supports that many; fewer evidence-backed candidates are valid, never padded) with evidence-for \u002F evidence-against and confidence per item. Validate the analyst contract before consuming advice. If no delegation tool is available, rank the same evidence-backed candidates inline; do not attempt tool-specific named-agent syntax from another runtime.\n\n### Phase 2: Pattern Analysis\n\nFind the pattern before fixing.\n\n1. **Find a working example in the same codebase.** What similar code works? Read it end-to-end (not just the location, not just nearby patterns).\n2. **Compare against the reference.** List every difference between the broken and the working version — including ones you think \"cannot matter\". Most root causes hide in the \"cannot matter\" set.\n3. **Understand dependencies.** What other components, settings, env vars, and assumptions does the working pattern rely on? Verify the broken version satisfies each.\n\nPhase 2 exit condition: a concrete diff between the broken and working version, with each row marked \"matters\" \u002F \"neutral\".\n\n### Phase 3: Hypothesis and Testing\n\nApply the scientific method.\n\n1. **Rank 3–5 falsifiable candidate hypotheses** after reproduction and pattern analysis, each with evidence for and against. When evidence supports fewer than three, rank only the evidence-backed candidates and never pad the list: a single evidence-backed candidate is enough to proceed. Return `NEEDS_CONTEXT` with the highest-information probe only when no candidate is evidence-backed. Show the ranking before testing; non-interactive execution selects the highest-ranked candidate without waiting.\n2. **Test one hypothesis at a time.** State \"X is the root cause because Y; minimal change Z should fix it.\" Change one variable per experiment. Do not layer a new fix on a failed one.\n3. **Update the ranking from evidence.** Pass → Phase 4; fail → reject or refine the hypothesis and record the result. After two rejected hypotheses, re-investigate before testing a third. A reverted falsification experiment is not a failed fix; count an attempted fix when it fails to resolve the confirmed reproduction or introduces a regression.\n4. **Stop after three failed fixes on the same surface.** The architecture-suspicion gate may request one independent analyst pass, when delegation is available, using `Caller: ywc-debug-rootcause`, `analysis_mode=debug_hypotheses`, the bounded packet, ranked hypotheses and failed-fix log. Require `Fix #4 signal: fix harder` and `Next fix worth attempting: \u003Cone concrete minimal change>`. Allow exactly one final fourth fix only when both fields are present, separate, evidence-linked, and returned for the valid debug pair. One missing or unlinked field, a different mode, malformed output or unavailable analyst keeps the stop in force. After a failed fourth fix, stop; do not reset the counter or attempt a fifth fix. Route architectural concerns to `ywc-architect`; the analyst recommends review and never makes the final architecture decision.\n\nPhase 3 exit condition: a passing test that confirms the hypothesis, with one and only one variable changed.\n\n### Phase 4: Implementation\n\nFix the root cause, not the symptom.\n\n1. **Create a failing test that captures the bug.** Simplest possible reproduction. The test must fail before the fix and pass after. This is the regression guard.\n2. **Implement a single fix.** Address the root cause only. No \"while I'm here\" cleanup, no preemptive refactoring of adjacent code.\n3. **Verify the fix.** Run the regression test plus the broader suite. Use `ywc-verify-done` to gate the completion claim.\n4. **Verify the regression test.** Revert the fix → test must FAIL. Restore the fix → test must PASS. (Red-green-red cycle. Without this, the test may be passing for reasons unrelated to the fix.)\n5. **If 3+ fixes failed on the same surface, STOP and question architecture.**\n\n   Signals of architectural problem:\n   - Each fix moves the defect to a new location.\n   - Each fix requires \"massive refactoring\" to implement cleanly.\n   - The pattern itself does not match the requirement.\n\n   Without both validated debug-mode analyst fields from Phase 3 step 4, **do not attempt fix #4**. Surface the situation to the user with: (a) the three attempted fixes and why each failed, (b) the architectural concern, (c) a proposed redesign or pattern change. The exception permits one minimal attempt only, followed by the original verification gate. See [references\u002Farchitectural-stop-signals.md](references\u002Farchitectural-stop-signals.md) for the surface format.\n\nPhase 4 exit condition: regression test passes + red-green-red cycle verified + `ywc-verify-done` block surfaced.\n\n## Red Flags — STOP and return to Phase 1\n\nIf you catch yourself doing any of these, stop and restart from Phase 1.\n\n| Red flag | Why it means stop |\n|---|---|\n| \"Quick fix for now, investigate later\" | \"Later\" never comes; the symptom-fix becomes the de facto code. |\n| \"Let me try changing X and see if it works\" | Trying is not testing. Form a hypothesis first. |\n| \"Multiple changes at once — faster\" | Bundled changes cannot be isolated. If the suite passes, you do not know *which* change fixed it. |\n| \"Skip the test, I'll verify manually\" | Manual verification does not protect against regression. |\n| \"Probably X, let me fix that\" | \"Probably\" is forbidden by `ywc-verify-done`. State the hypothesis precisely or do not state it. |\n| \"Pattern says X but I'll adapt differently\" | Partial understanding of a pattern guarantees a bug. Read it completely before adapting. |\n| \"Here are the main problems: [list of fixes]\" | Listing fixes without investigation = guessing in bulk. |\n| \"One more fix attempt\" (after 2+) | Three failed fixes require the architecture gate; only both validated debug-mode fields permit one final attempt. |\n| Each fix surfaces a new defect elsewhere | The pattern is wrong, not the latest line. |\n\n## Output Format\n\nSurface the investigation in this shape, in order:\n\n````markdown\n### Investigation summary\n\n- **Symptom:** \u003Cone-line observed behavior>\n- **Reproduction:** \u003Cexact command(s), or manual evidence and constraints>\n- **Feedback loop \u002F Catches \u002F Misses:** \u003Cminimal observation and limits>\n- **Ranked candidates:** \u003C1–5 evidence-backed falsifiable hypotheses (3–5 when evidence supports), evidence for\u002Fagainst>\n- **Root cause (Phase 1):** \u003Cone-sentence why, with file:line citation>\n- **Working reference (Phase 2):** \u003Cpath:line of a working sibling, if applicable; \"N\u002FA — no sibling pattern exists\" otherwise>\n- **Hypothesis (Phase 3):** \"\u003CX is the root cause because Y. Minimal change Z should fix it.>\"\n- **Fix attempted:** \u003Ccommit hash or file:line of the change>\n- **Regression test:** \u003Ctest path:name>\n\n### Verification\n\n(verification block per `ywc-verify-done`, including red-green-red proof for the regression test)\n````\n\nWhen the investigation reveals an architectural concern (Phase 4 §5), the output instead surfaces a `### Architectural concern` block and the conversation transfers to the user for design discussion — no Phase 4 §1–4 occurs in that path.\n\n## Integration\n\n- **Upstream callers:** `ywc-verify-done` (when verification fails ≥2 times on the same surface), `ywc-impl-review` (when a Critical finding points to a defect with unclear root cause), `ywc-incident-postmortem` (live debugging that escalates into a postmortem still uses these 4 phases).\n- **Downstream:** `ywc-verify-done` (Phase 4 §3 — gate the fix's completion claim), `ywc-plan` (when architectural redesign is required after Phase 4 §5).\n- **Pairs with:** `ywc-impl-review` (when investigation reveals a class of defects, not a single one), `ywc-incident-postmortem` (post-resolution write-up).\n\n## Validation Checklist\n\nBefore concluding the investigation, verify:\n\n- [ ] Phase 1 produced a one-sentence root-cause statement with `file:line` citation\n- [ ] Minimal feedback loop, observed failure and catches\u002Fmisses recorded; manual evidence and constraints named when automation is unavailable\n- [ ] Phase 2 found at least one working reference, OR explicitly recorded `N\u002FA — no sibling pattern exists`\n- [ ] Hypothesis (Phase 3) is in the shape \"X is the root cause because Y; minimal change Z fixes it\"\n- [ ] The fix changed exactly one variable; no bundled cleanup\n- [ ] A regression test was added before the fix and verified red-green-red\n- [ ] `ywc-verify-done` block was surfaced for the final passing test\n- [ ] After three failed fixes, stop unless both validated debug-mode fields permit one fourth fix; stop after a failed fourth fix\n\n## Common Mistakes\n\n- **Reading the source without first instrumenting boundaries** in multi-component systems. Source-reading produces hypotheses about which component is at fault; only boundary logs produce *evidence* of which component is at fault.\n- **Treating \"no root cause found\" as a conclusion.** ≥95% of such conclusions are incomplete investigations. If after 30 minutes the root cause is still elusive, the investigation strategy is wrong (wrong tools, wrong layer, wrong reproduction). Change strategy; do not declare \"environmental flake\" and move on.\n- **Reverting the fix without re-verifying the regression test** (skipping the red-green-red cycle). Without the revert step, the test may have been passing for a reason unrelated to the fix.\n- **Allowing the fix to bundle adjacent improvements.** \"While I'm here\" turns the single-variable change into an N-variable change and destroys the bisection signal if the bug returns.\n\n## References\n\n| Reference | Use when |\n|---|---|\n| [references\u002Ffour-phase-checklist.md](references\u002Ffour-phase-checklist.md) | Walking through the 4 phases with concrete checklists per phase |\n| [references\u002Farchitectural-stop-signals.md](references\u002Farchitectural-stop-signals.md) | Deciding whether the situation is \"next fix is right\" vs \"architecture is wrong\" |\n| [..\u002Freferences\u002Fnon-stop-execution.md](..\u002Freferences\u002Fnon-stop-execution.md) | Routing the investigation result back into the executor loop without halting the workflow unnecessarily |\n","# ywc-debug-rootcause\n\n**Announce at start:** \"I'm using the ywc-debug-rootcause skill to identify root cause through 4-phase investigation before any fix is proposed.\"\n\nThis skill enforces the discipline of finding the **why** before touching the **what**. It exists because guess-and-fix loops produce three failure modes that ywc workflows must avoid: (1) symptom fixes that mask the real defect and surface elsewhere later; (2) compounding edits that make the next investigation harder; (3) \"architecture wrong\" cases mistaken for \"fix harder\" cases, wasting 3–10× the rework. Adapted from `superpowers:systematic-debugging`.\n\n## The Iron Law\n\n```text\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\n```\n\nIf Phase 1 has not been completed, fixes cannot be proposed. \"Try X and see\" is a guess, not an investigation.\n\n## Rationalization Defense\n\nWhen tempted to skip a phase, check this table first:\n\n| Excuse | Reality |\n|---|---|\n| \"I see the problem, let me just fix it\" | Seeing a *symptom* is not understanding the *cause*. The first reproducible defect-on-line-X is almost always a downstream effect of an upstream bad value. Trace the data flow at least one hop upstream before editing. |\n| \"Emergency, no time for the 4 phases\" | The 4 phases take 15–30 minutes for a typical bug; guess-and-check takes 2–3 hours of thrashing with a 40% first-time-fix rate. Pressure makes the systematic path **faster**, not slower. |\n| \"I'll try one quick fix, then investigate if it doesn't work\" | The first fix sets the pattern for the session. After the first symptom-fix, every subsequent attempt becomes \"fix something else\", not \"investigate\". Do the investigation first. |\n| \"I've already tried 3 fixes, one more should do it\" | Three failed fixes require the architecture-suspicion gate (Phase 4 §5). Stop by default; one fourth attempt requires both separate evidence-linked debug-mode analyst fields. A failed fourth attempt ends the loop. |\n| \"Test fails locally, I'll skip Phase 2 (pattern analysis) since I know the code\" | Familiarity is the failure mode. The \"I know this code\" agent skips reading the *working* sibling implementation and reinvents a bug the sibling already solved. Always read a working reference end-to-end before fixing the broken one. |\n| \"Logging at boundaries is overkill, I'll just read the source\" | Multi-component systems (CI → build → sign; API → service → DB; controller → middleware → handler) fail at boundaries, not inside components. Source-reading without boundary logging produces false hypotheses about which component is at fault. |\n| \"Symptom is intermittent, must be flakiness\" | \"Flakiness\" is the label agents give to bugs they did not investigate. ≥95% of \"flaky test\" diagnoses turn out to be reproducible race conditions or environment leaks once instrumented. Skip the flakiness label and investigate. |\n| \"I'll fix this AND clean up the surrounding code while I'm here\" | Bundled changes mean you cannot tell which change fixed the bug, and the cleanup may *cause* a new bug. One investigation → one fix → one verification. Refactor in a separate session. |\n\n**Violating the letter of these rules is violating the spirit.** The 4 phases exist because each one catches a class of failure the others miss.\n\n## When to Use\n\nUse for **any** technical defect, including:\n\n- Test failure (unit, integration, E2E)\n- Production bug\n- Build failure \u002F compilation error\n- Type-check error that resists obvious fix\n- Performance regression\n- Integration \u002F cross-component failure\n- Unexpected behavior in code that \"used to work\"\n\nUse this **especially** when:\n\n- Under time pressure (the temptation to guess peaks here)\n- A previous fix attempt did not work\n- The symptom is intermittent or environment-dependent\n- \"Just one quick fix\" feels obvious\n\nDo **not** skip when:\n\n- The bug looks \"simple\" — simple bugs have causes too\n- The user is impatient — systematic is still faster than thrashing\n- You are tired — exhaustion is not a justification\n\n## Analyst contract\n\nEvery analyst packet carries `Caller: ywc-debug-rootcause` and `analysis_mode=debug_hypotheses` plus bounded evidence. Missing, unknown, or mismatched caller\u002Fmode returns `NEEDS_CONTEXT` without inferring another mode. Validate the returned Status\u002FSummary\u002FFinding counts envelope and matching Analysis mode before consuming advice; owner\u002Finput\u002Foutput\u002Fstatus mismatch returns `NEEDS_CONTEXT`. An analyst refusal consumes the existing dispatch budget; preserve the caller's original gate and surface the missing evidence instead of re-dispatching or falling through. The analyst returns inline advice and never writes the caller's report or runs probes. Unavailable delegation uses the documented inline path; unavailable live runtime evidence is `UNVERIFIED — instruction contract only`.\n\n## The Four Phases\n\nComplete each phase before proceeding to the next.\n\n### Phase 1: Root-Cause Investigation\n\nBefore proposing **any** fix:\n\n0. **Establish the smallest feedback loop first.** Use a focused test, build check, script or bounded manual reproduction. Record `Feedback loop`, `Catches`, `Misses`, and the observed failure before any fix. If automated reproduction is unavailable, record manual evidence and constraints; do not fabricate RED or claim execution PASS. Read-only analyst advice is not a reproduced failure.\n1. **Read error messages carefully.** Read the full stack trace, every line. Note file paths, line numbers, error codes. Errors often contain the exact name of the missing thing.\n2. **Reproduce consistently.** Run the minimal feedback loop until its result is predictable. If reproduction is unavailable, retain the manual evidence and constraints from step 0, gather the missing data and do not propose a speculative fix.\n3. **Check recent changes.** Run `git log --oneline -20`, `git diff HEAD~1`, check dependency bumps, environment changes, config changes since the last known-good state.\n4. **Add diagnostic instrumentation at component boundaries.** For multi-component systems, the failure is almost always at a boundary, not inside a component. Log what each component receives and what it emits. Run once to gather evidence. **Read the evidence before forming a hypothesis.**\n5. **Trace data flow upstream.** Where does the bad value originate? What called the failing function with that value? Keep tracing until the *origin* is found; fix at the origin, not at the symptom.\n\nPhase 1 exit condition: you can answer in one sentence **what** is wrong and **why** it is happening. If either answer is fuzzy, continue Phase 1.\n\nWhen local evidence cannot produce a confident initial hypothesis and the current Codex session has an available subagent\u002Fdelegation tool, request at most one independent `ywc-root-cause-analyst` pass. Send `Caller: ywc-debug-rootcause`, `analysis_mode=debug_hypotheses`, and only a bounded packet: failure symptom, timeline, stack trace or logs, recent diff, rejected hypotheses, relevant code snippet, and current candidate cause. Ask for `Status: \u003CDONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT>` plus ranked, falsifiable hypotheses (3–5 when evidence supports that many; fewer evidence-backed candidates are valid, never padded) with evidence-for \u002F evidence-against and confidence per item. Validate the analyst contract before consuming advice. If no delegation tool is available, rank the same evidence-backed candidates inline; do not attempt tool-specific named-agent syntax from another runtime.\n\n### Phase 2: Pattern Analysis\n\nFind the pattern before fixing.\n\n1. **Find a working example in the same codebase.** What similar code works? Read it end-to-end (not just the location, not just nearby patterns).\n2. **Compare against the reference.** List every difference between the broken and the working version — including ones you think \"cannot matter\". Most root causes hide in the \"cannot matter\" set.\n3. **Understand dependencies.** What other components, settings, env vars, and assumptions does the working pattern rely on? Verify the broken version satisfies each.\n\nPhase 2 exit condition: a concrete diff between the broken and working version, with each row marked \"matters\" \u002F \"neutral\".\n\n### Phase 3: Hypothesis and Testing\n\nApply the scientific method.\n\n1. **Rank 3–5 falsifiable candidate hypotheses** after reproduction and pattern analysis, each with evidence for and against. When evidence supports fewer than three, rank only the evidence-backed candidates and never pad the list: a single evidence-backed candidate is enough to proceed. Return `NEEDS_CONTEXT` with the highest-information probe only when no candidate is evidence-backed. Show the ranking before testing; non-interactive execution selects the highest-ranked candidate without waiting.\n2. **Test one hypothesis at a time.** State \"X is the root cause because Y; minimal change Z should fix it.\" Change one variable per experiment. Do not layer a new fix on a failed one.\n3. **Update the ranking from evidence.** Pass → Phase 4; fail → reject or refine the hypothesis and record the result. After two rejected hypotheses, re-investigate before testing a third. A reverted falsification experiment is not a failed fix; count an attempted fix when it fails to resolve the confirmed reproduction or introduces a regression.\n4. **Stop after three failed fixes on the same surface.** The architecture-suspicion gate may request one independent analyst pass, when delegation is available, using `Caller: ywc-debug-rootcause`, `analysis_mode=debug_hypotheses`, the bounded packet, ranked hypotheses and failed-fix log. Require `Fix #4 signal: fix harder` and `Next fix worth attempting: \u003Cone concrete minimal change>`. Allow exactly one final fourth fix only when both fields are present, separate, evidence-linked, and returned for the valid debug pair. One missing or unlinked field, a different mode, malformed output or unavailable analyst keeps the stop in force. After a failed fourth fix, stop; do not reset the counter or attempt a fifth fix. Route architectural concerns to `ywc-architect`; the analyst recommends review and never makes the final architecture decision.\n\nPhase 3 exit condition: a passing test that confirms the hypothesis, with one and only one variable changed.\n\n### Phase 4: Implementation\n\nFix the root cause, not the symptom.\n\n1. **Create a failing test that captures the bug.** Simplest possible reproduction. The test must fail before the fix and pass after. This is the regression guard.\n2. **Implement a single fix.** Address the root cause only. No \"while I'm here\" cleanup, no preemptive refactoring of adjacent code.\n3. **Verify the fix.** Run the regression test plus the broader suite. Use `ywc-verify-done` to gate the completion claim.\n4. **Verify the regression test.** Revert the fix → test must FAIL. Restore the fix → test must PASS. (Red-green-red cycle. Without this, the test may be passing for reasons unrelated to the fix.)\n5. **If 3+ fixes failed on the same surface, STOP and question architecture.**\n\n   Signals of architectural problem:\n   - Each fix moves the defect to a new location.\n   - Each fix requires \"massive refactoring\" to implement cleanly.\n   - The pattern itself does not match the requirement.\n\n   Without both validated debug-mode analyst fields from Phase 3 step 4, **do not attempt fix #4**. Surface the situation to the user with: (a) the three attempted fixes and why each failed, (b) the architectural concern, (c) a proposed redesign or pattern change. The exception permits one minimal attempt only, followed by the original verification gate. See [references\u002Farchitectural-stop-signals.md](references\u002Farchitectural-stop-signals.md) for the surface format.\n\nPhase 4 exit condition: regression test passes + red-green-red cycle verified + `ywc-verify-done` block surfaced.\n\n## Red Flags — STOP and return to Phase 1\n\nIf you catch yourself doing any of these, stop and restart from Phase 1.\n\n| Red flag | Why it means stop |\n|---|---|\n| \"Quick fix for now, investigate later\" | \"Later\" never comes; the symptom-fix becomes the de facto code. |\n| \"Let me try changing X and see if it works\" | Trying is not testing. Form a hypothesis first. |\n| \"Multiple changes at once — faster\" | Bundled changes cannot be isolated. If the suite passes, you do not know *which* change fixed it. |\n| \"Skip the test, I'll verify manually\" | Manual verification does not protect against regression. |\n| \"Probably X, let me fix that\" | \"Probably\" is forbidden by `ywc-verify-done`. State the hypothesis precisely or do not state it. |\n| \"Pattern says X but I'll adapt differently\" | Partial understanding of a pattern guarantees a bug. Read it completely before adapting. |\n| \"Here are the main problems: [list of fixes]\" | Listing fixes without investigation = guessing in bulk. |\n| \"One more fix attempt\" (after 2+) | Three failed fixes require the architecture gate; only both validated debug-mode fields permit one final attempt. |\n| Each fix surfaces a new defect elsewhere | The pattern is wrong, not the latest line. |\n\n## Output Format\n\nSurface the investigation in this shape, in order:\n\n````markdown\n### Investigation summary\n\n- **Symptom:** \u003Cone-line observed behavior>\n- **Reproduction:** \u003Cexact command(s), or manual evidence and constraints>\n- **Feedback loop \u002F Catches \u002F Misses:** \u003Cminimal observation and limits>\n- **Ranked candidates:** \u003C1–5 evidence-backed falsifiable hypotheses (3–5 when evidence supports), evidence for\u002Fagainst>\n- **Root cause (Phase 1):** \u003Cone-sentence why, with file:line citation>\n- **Working reference (Phase 2):** \u003Cpath:line of a working sibling, if applicable; \"N\u002FA — no sibling pattern exists\" otherwise>\n- **Hypothesis (Phase 3):** \"\u003CX is the root cause because Y. Minimal change Z should fix it.>\"\n- **Fix attempted:** \u003Ccommit hash or file:line of the change>\n- **Regression test:** \u003Ctest path:name>\n\n### Verification\n\n(verification block per `ywc-verify-done`, including red-green-red proof for the regression test)\n````\n\nWhen the investigation reveals an architectural concern (Phase 4 §5), the output instead surfaces a `### Architectural concern` block and the conversation transfers to the user for design discussion — no Phase 4 §1–4 occurs in that path.\n\n## Integration\n\n- **Upstream callers:** `ywc-verify-done` (when verification fails ≥2 times on the same surface), `ywc-impl-review` (when a Critical finding points to a defect with unclear root cause), `ywc-incident-postmortem` (live debugging that escalates into a postmortem still uses these 4 phases).\n- **Downstream:** `ywc-verify-done` (Phase 4 §3 — gate the fix's completion claim), `ywc-plan` (when architectural redesign is required after Phase 4 §5).\n- **Pairs with:** `ywc-impl-review` (when investigation reveals a class of defects, not a single one), `ywc-incident-postmortem` (post-resolution write-up).\n\n## Validation Checklist\n\nBefore concluding the investigation, verify:\n\n- [ ] Phase 1 produced a one-sentence root-cause statement with `file:line` citation\n- [ ] Minimal feedback loop, observed failure and catches\u002Fmisses recorded; manual evidence and constraints named when automation is unavailable\n- [ ] Phase 2 found at least one working reference, OR explicitly recorded `N\u002FA — no sibling pattern exists`\n- [ ] Hypothesis (Phase 3) is in the shape \"X is the root cause because Y; minimal change Z fixes it\"\n- [ ] The fix changed exactly one variable; no bundled cleanup\n- [ ] A regression test was added before the fix and verified red-green-red\n- [ ] `ywc-verify-done` block was surfaced for the final passing test\n- [ ] After three failed fixes, stop unless both validated debug-mode fields permit one fourth fix; stop after a failed fourth fix\n\n## Common Mistakes\n\n- **Reading the source without first instrumenting boundaries** in multi-component systems. Source-reading produces hypotheses about which component is at fault; only boundary logs produce *evidence* of which component is at fault.\n- **Treating \"no root cause found\" as a conclusion.** ≥95% of such conclusions are incomplete investigations. If after 30 minutes the root cause is still elusive, the investigation strategy is wrong (wrong tools, wrong layer, wrong reproduction). Change strategy; do not declare \"environmental flake\" and move on.\n- **Reverting the fix without re-verifying the regression test** (skipping the red-green-red cycle). Without the revert step, the test may have been passing for a reason unrelated to the fix.\n- **Allowing the fix to bundle adjacent improvements.** \"While I'm here\" turns the single-variable change into an N-variable change and destroys the bisection signal if the bug returns.\n\n## References\n\n| Reference | Use when |\n|---|---|\n| [references\u002Ffour-phase-checklist.md](references\u002Ffour-phase-checklist.md) | Walking through the 4 phases with concrete checklists per phase |\n| [references\u002Farchitectural-stop-signals.md](references\u002Farchitectural-stop-signals.md) | Deciding whether the situation is \"next fix is right\" vs \"architecture is wrong\" |\n| [..\u002Freferences\u002Fnon-stop-execution.md](..\u002Freferences\u002Fnon-stop-execution.md) | Routing the investigation result back into the executor loop without halting the workflow unnecessarily |\n",{"name":5,"description":7},"main","7e8ac872e53df8c89d75663e031626281a2a2f5c","codex\u002Fskills\u002Fywc-debug-rootcause",1,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit","https:\u002F\u002Fgithub.com\u002Fyongwoon","https:\u002F\u002Fwww.webhani.com","2026-11-08 17:14:59",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-debug-rootcause",{"tool":37,"command":38},"bunx","bunx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-debug-rootcause",{"tool":40,"command":41},"pnpm","pnpm dlx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-debug-rootcause","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002FSKILL.md",true,[45,51,55,59,63,67,71,75,79,83],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"agents\u002Fopenai.yaml","REFERENCE","参考文档",451,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002Fagents\u002Fopenai.yaml",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"evals\u002Fevals.json",5457,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002Fevals\u002Fevals.json",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"README.en.md",3385,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002FREADME.en.md",{"path":60,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":61,"sourceHtmlUrl":62},"README.es.md",1132,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002FREADME.es.md",{"path":64,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":65,"sourceHtmlUrl":66},"README.ja.md",3486,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002FREADME.ja.md",{"path":68,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":69,"sourceHtmlUrl":70},"README.ko.md",3542,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002FREADME.ko.md",{"path":72,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":73,"sourceHtmlUrl":74},"README.md",3535,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002FREADME.md",{"path":76,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":77,"sourceHtmlUrl":78},"README.zh.md",984,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002FREADME.zh.md",{"path":80,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Farchitectural-stop-signals.md",5882,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002Freferences\u002Farchitectural-stop-signals.md",{"path":84,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":85,"sourceHtmlUrl":86},"references\u002Ffour-phase-checklist.md",6248,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fcodex\u002Fskills\u002Fywc-debug-rootcause\u002Freferences\u002Ffour-phase-checklist.md",[88,94,100,107,114,121],{"skillNo":89,"name":90,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":18},"01M72TQ84GTCPCV2VJ778V17TW","missing-frontmatter","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002Fmissing-frontmatter\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":18},"01M72TQ6M4BFWE7P9EPW0GZDCM","malformed-frontmatter","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002Fmalformed-frontmatter\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":18},"01M72TQ3ESGKXZ4QRWGTX92BKJ","fixture-501-fail","(ywc) Use when aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa Do not use for x.","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002F501-fail\u002FSKILL.md",[],[],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":18},"01M72TQ0HJ8H3R37J9WPWGKJZR","fixture-500-pass","(ywc) Use when aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa Do not use for x.","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002F500-pass\u002FSKILL.md",[],[],{"skillNo":115,"name":116,"nameZh":6,"description":117,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":118,"categories":119,"keywords":120,"publishedAt":18},"01M72TPWNCC7NEYD0D9N12KSQS","ywc-worktrees","(ywc) Use when creating, auditing, pruning, or resolving git worktrees for isolated task workspaces, whether delegated from an executor or used standalone. Triggers: \"worktree 생성\", \"worktree audit\", \"worktree 정리\", \"worktree prune\", \"ywc-worktrees\", \"create worktree\". Do not use for branch creation\u002Fdeletion alone, PR creation (use ywc-create-pr), CI or merge delivery (use ywc-finish-branch), task orchestration (use ywc-sequential-executor or ywc-parallel-executor), or non-git isolation.","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-worktrees\u002FSKILL.md",[],[],{"skillNo":122,"name":123,"nameZh":6,"description":124,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":125,"categories":126,"keywords":127,"publishedAt":18},"01M72TPRNR3E6QWB91GM98ABBV","ywc-wayfinder","(ywc) Use when a large or uncertain change needs multi-session discovery with a deterministic local map and exactly one active ticket before planning or implementation. Triggers: \"wayfinder\", \"길찾기\", \"discovery map\", \"multi-session discovery\", \"탐색 ticket\", \"経路整理\", \"探索マップ\", \"ywc-wayfinder\". Do not use for ordinary planning (use ywc-plan), idea clarification (use ywc-brainstorm), direct implementation, or tracker\u002Fdatabase writes outside the local Markdown map.","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-wayfinder\u002FSKILL.md",[],[]]