<skill_overview> Structure and plan code fixes before implementation to ensure safe, testable, and reversible changes

Bug report or issue needs to be analyzed and fixed Error in production or tests needs investigation Refactoring required to fix underlying problem Need to plan a fix before writing code Complex fix spanning multiple files or modules

</skill_overview> <clarification_strategy> <when_to_ask> Issue description is vague or incomplete Multiple possible interpretations of the problem Need to confirm reproduction steps Unclear which behavior is expected vs actual Fix has significant trade-offs requiring user decision </when_to_ask> <how_to_ask> Use the "question" tool to ask clarifying questions Ask specific, actionable questions (not open-ended) Batch related questions together (max 2-3 at once) Provide context why you're asking </how_to_ask>

<good_question> The error occurs on login, but I found two auth flows. Is this happening with OAuth login, password login, or both? </good_question> <good_question> I can fix this with a null check (quick) or by refactoring the data flow (proper). Should I do a minimal fix now, or a more thorough refactoring? </good_question> <bad_question> What's wrong? <why_bad>Too vague, doesn't show any analysis effort</why_bad> </bad_question>

</clarification_strategy> <root_cause_analysis>

Iteratively ask "why?" to peel away symptom layers until reaching actionable root cause

Stop when you reach an actionable systemic issue (3-7 iterations typical) Don't settle for surface-level causes or "human error" Focus on processes/systems, not individuals Keep asking until you hit your influence boundary

Users unable to login Authentication service returns 500 error Database connection pool exhausted Connections not being released Error handling in async function doesn't close connections Missing try-finally block in database client wrapper <root_cause>Missing error handling that properly closes database connections</root_cause>

Reproduce reliably — create minimal, deterministic reproduction steps Gather observability data — metrics (what's wrong) → logs (what happened) → traces (where/why) Isolate the scope — binary search through code/system layers Form hypothesis — write down your theory before diving into code Verify fix — not just "it works" but that the bug scenario is addressed

</root_cause_analysis> <planning_phases>

Read the issue/bug report completely Identify symptoms vs root cause (symptoms ≠ cause) Determine reproduction steps Check if issue is intermittent or consistent Use "question" tool if critical info is missing

Clear problem statement with reproduction steps