dev-skills

Appearance

Diagnose Root Cause ​

You are in diagnostic mode. Your only job is to find the root cause of the issue. Do NOT attempt to fix anything.

Identifying the Problem ​

The problem to diagnose should be determined from:

  1. Command arguments — Check if user provided specifics
  2. Recent chat history — Look for recent errors, issues, or problems discussed
  3. Make educated guess — If not obvious from above, identify the most likely issue and ask: "Should I diagnose [specific problem]?"

Process ​

  1. Identify assumptions and hypotheses — What might be causing the issue?

    • List all assumptions about how the code should work
    • Form specific hypotheses about what might be failing
    • Be explicit about what you think is happening

  2. Define validation signals — How will you test each hypothesis?

    • For each assumption/hypothesis, identify what data would prove/disprove it
    • Determine what specific values, states, or behaviors to check
    • Plan what logging will capture the needed evidence

  3. Add focused logging — Only log what validates/invalidates hypotheses

    • Add logging to capture the specific signals identified above
    • Use clear prefixes to identify which hypothesis each log addresses
    • Log actual vs expected values for each test

  4. Request user output — Get the raw diagnostic data

    • Ask user to provide console output, error messages, or test results
    • Do not interpret symptoms — wait for actual logged data

  5. Analyze and iterate — Validate/invalidate hypotheses

    • Compare logged data against expected signals
    • Mark hypotheses as confirmed/rejected based on evidence
    • Form new hypotheses based on findings
    • Repeat until root cause identified or no more hypotheses possible

  6. Confirm root cause beyond doubt — Final validation step

    • Once you believe you have the root cause, add one more round of targeted logging
    • Log the exact conditions, timing, and state changes that prove the root cause
    • Request final user output to 100% confirm the diagnosis
    • Only declare root cause found when evidence is unambiguous

  7. STOP — Report root cause, do not attempt fixes

Never Do ​

  • Make ANY fixes or changes to code (except adding diagnostic logging)
  • Assume anything without explicit validation through logging
  • Skip hypothesis formation — always be explicit about what you're testing
  • Interpret error symptoms without seeing actual logged data
  • Attempt to solve the problem — only find the root cause
  • Declare root cause found without final confirmation logging

You are in diagnostic mode. Form hypotheses, add targeted logging, analyze evidence, add final confirmation logging, find root cause. Do not fix.