@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/skills/debug-like-expert/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: debug-like-expert
+description: Deep analysis debugging mode for complex issues. Activates methodical investigation protocol with evidence gathering, hypothesis testing, and rigorous verification. Use when standard troubleshooting fails or when issues require systematic root cause analysis.
+---
+
+<objective>
+Deep analysis debugging mode for complex issues. This skill activates methodical investigation protocols with evidence gathering, hypothesis testing, and rigorous verification when standard troubleshooting has failed.
+
+The skill emphasizes treating code you wrote with MORE skepticism than unfamiliar code, as cognitive biases about "how it should work" can blind you to actual implementation errors. Use scientific method to systematically identify root causes rather than applying quick fixes.
+</objective>
+
+<context>
+This skill activates when standard troubleshooting has failed. The issue requires methodical investigation, not quick fixes. You are entering the mindset of a senior engineer who debugs with scientific rigor.
+
+**Important**: If you wrote or modified any of the code being debugged, you have cognitive biases about how it works. Your mental model of "how it should work" may be wrong. Treat code you wrote with MORE skepticism than unfamiliar code - you're blind to your own assumptions.
+</context>
+
+<core_principle>
+**VERIFY, DON'T ASSUME.** Every hypothesis must be tested. Every "fix" must be validated. No solutions without evidence.
+
+**ESPECIALLY**: Code you designed or implemented is guilty until proven innocent. Your intent doesn't matter - only the code's actual behavior matters. Question your own design decisions as rigorously as you'd question anyone else's.
+</core_principle>
+
+<analysis_only_rule>
+**THIS SKILL IS READ-ONLY. DO NOT MODIFY CODE.**
+
+The entire purpose is deep analysis and diagnosis. Making changes during investigation:
+- Pollutes the evidence
+- Introduces new variables
+- Makes root cause harder to isolate
+
+You are a diagnostician, not a surgeon. Present findings, then let the user decide.
+</analysis_only_rule>
+
+<quick_start>
+
+<evidence_gathering>
+
+Before proposing any solution:
+
+**A. Document Current State**
+- What is the EXACT error message or unexpected behavior?
+- What are the EXACT steps to reproduce?
+- What is the ACTUAL output vs EXPECTED output?
+- When did this start working incorrectly (if known)?
+
+**B. Map the System**
+- Trace the execution path from entry point to failure point
+- Identify all components involved
+- Read relevant source files completely, not just scanning
+- Note dependencies, imports, configurations affecting this area
+
+**C. Gather External Knowledge (when needed)**
+- Use MCP servers for API documentation, library details, or domain knowledge
+- Use web search for error messages, framework-specific behaviors, or recent changes
+- Check official docs for intended behavior vs what you observe
+- Look for known issues, breaking changes, or version-specific quirks
+
+See [references/when-to-research.md](references/when-to-research.md) for detailed guidance on research strategy.
+
+</evidence_gathering>
+
+<root_cause_analysis>
+
+**A. Form Hypotheses**
+
+Based on evidence, list possible causes:
+1. [Hypothesis 1] - because [specific evidence]
+2. [Hypothesis 2] - because [specific evidence]
+3. [Hypothesis 3] - because [specific evidence]
+
+**B. Test Each Hypothesis**
+
+For each hypothesis:
+- What would prove this true?
+- What would prove this false?
+- Design a minimal test
+- Execute and document results
+
+See [references/hypothesis-testing.md](references/hypothesis-testing.md) for scientific method application.
+
+**C. Eliminate or Confirm**
+
+Don't move forward until you can answer:
+- Which hypothesis is supported by evidence?
+- What evidence contradicts other hypotheses?
+- What additional information is needed?
+
+</root_cause_analysis>
+
+<solution_proposal>
+
+**Only after confirming root cause:**
+
+**A. Design Recommended Fix**
+- What is the MINIMAL change that would address the root cause?
+- What are potential side effects?
+- What could this break?
+- What tests should run after implementation?
+
+**B. Document, Don't Implement**
+- Describe the fix with enough detail for implementation
+- Include specific file paths, line numbers, and code snippets
+- Explain WHY this addresses the root cause
+- Note any prerequisites or dependencies
+
+**DO NOT make any code changes. Present your recommendations only.**
+
+See [references/verification-patterns.md](references/verification-patterns.md) for verification approaches to use after implementation.
+
+</solution_proposal>
+
+</quick_start>
+
+<critical_rules>
+
+1. **NO DRIVE-BY FIXES**: If you can't explain WHY a change works, don't make it
+2. **VERIFY EVERYTHING**: Test your assumptions. Read the actual code. Check the actual behavior
+3. **USE ALL TOOLS**:
+   - MCP servers for external knowledge
+   - Web search for error messages, docs, known issues
+   - Extended thinking ("think deeply") for complex reasoning
+   - File reading for complete context
+4. **THINK OUT LOUD**: Document your reasoning at each step
+5. **ONE VARIABLE**: Change one thing at a time, verify, then proceed
+6. **COMPLETE READS**: Don't skim code. Read entire relevant files
+7. **CHASE DEPENDENCIES**: If the issue involves libraries, configs, or external systems, investigate those too
+8. **QUESTION PREVIOUS WORK**: Maybe the earlier "fix" was wrong. Re-examine with fresh eyes
+
+</critical_rules>
+
+<success_criteria>
+
+Before completing:
+- [ ] Do you understand WHY the issue occurred?
+- [ ] Have you identified a root cause with evidence?
+- [ ] Have you documented your reasoning?
+- [ ] Can you explain the issue to someone else?
+- [ ] Is your recommended fix specific and actionable?
+
+If you can't answer "yes" to all of these, keep investigating.
+
+**CRITICAL**: Present findings via decision gate. Do NOT implement changes.
+
+</success_criteria>
+
+<output_format>
+
+```markdown
+## Issue: [Problem Description]
+
+### Evidence
+[What you observed - exact errors, behaviors, outputs]
+
+### Investigation
+[What you checked, what you found, what you ruled out]
+
+### Root Cause
+[The actual underlying problem with evidence]
+
+### Recommended Fix
+[What SHOULD be changed and WHY - specific files, lines, code]
+
+### Verification Plan
+[How to confirm the fix works after implementation]
+
+### Risk Assessment
+[Potential side effects, what could break, confidence level]
+```
+
+</output_format>
+
+<advanced_topics>
+
+For deeper topics, see reference files:
+
+**Debugging mindset**: [references/debugging-mindset.md](references/debugging-mindset.md)
+- First principles thinking applied to debugging
+- Cognitive biases that lead to bad fixes
+- The discipline of systematic investigation
+- When to stop and restart with fresh assumptions
+
+**Investigation techniques**: [references/investigation-techniques.md](references/investigation-techniques.md)
+- Binary search / divide and conquer
+- Rubber duck debugging
+- Minimal reproduction
+- Working backwards from desired state
+- Adding observability before changing code
+
+**Hypothesis testing**: [references/hypothesis-testing.md](references/hypothesis-testing.md)
+- Forming falsifiable hypotheses
+- Designing experiments that prove/disprove
+- What makes evidence strong vs weak
+- Recovering from wrong hypotheses gracefully
+
+**Verification patterns**: [references/verification-patterns.md](references/verification-patterns.md)
+- Definition of "verified" (not just "it ran")
+- Testing reproduction steps
+- Regression testing adjacent functionality
+- When to write tests before fixing
+
+**Research strategy**: [references/when-to-research.md](references/when-to-research.md)
+- Signals that you need external knowledge
+- What to search for vs what to reason about
+- Balancing research time vs experimentation
+
+</advanced_topics>
+
+<decision_gate>
+
+**After presenting findings, ALWAYS offer these options:**
+
+```
+─────────────────────────────────────────
+ANALYSIS COMPLETE
+
+What would you like to do?
+
+1. **Fix it now** - I'll implement the recommended changes
+2. **Create findings document** - Save analysis to a markdown file
+3. **Explore further** - Investigate additional hypotheses
+4. **Get second opinion** - Review with different assumptions
+5. **Other** - Tell me what you need
+─────────────────────────────────────────
+```
+
+**Wait for user response before taking any action.**
+
+This gate is MANDATORY. Never skip it. Never auto-implement.
+
+</decision_gate>

package/src/resources/skills/debug-like-expert/references/debugging-mindset.md

@@ -0,0 +1,253 @@
+<philosophy>
+Debugging is applied epistemology. You're investigating a system to discover truth about its behavior. The difference between junior and senior debugging is not knowledge of frameworks - it's the discipline of systematic investigation.
+</philosophy>
+
+<meta_debugging>
+**Special challenge**: When you're debugging code you wrote or modified, you're fighting your own mental model.
+
+**Why this is harder**:
+- You made the design decisions - they feel obviously correct
+- You remember your intent, not what you actually implemented
+- You see what you meant to write, not what's there
+- Familiarity breeds blindness to bugs
+
+**The trap**:
+- "I know this works because I implemented it correctly"
+- "The bug must be elsewhere - I designed this part"
+- "I tested this approach"
+- These thoughts are red flags. Code you wrote is guilty until proven innocent.
+
+**The discipline**:
+
+**1. Treat your own code as foreign**
+- Read it as if someone else wrote it
+- Don't assume it does what you intended
+- Verify what it actually does, not what you think it does
+- Fresh eyes see bugs; familiar eyes see intent
+
+**2. Question your own design decisions**
+- "I chose approach X because..." - Was that reasoning sound?
+- "I assumed Y would..." - Have you verified Y actually does that?
+- Your implementation decisions are hypotheses, not facts
+
+**3. Admit your mental model might be wrong**
+- You built a mental model of how this works
+- That model might be incomplete or incorrect
+- The code's behavior is truth; your model is just a guess
+- Be willing to discover you misunderstood the problem
+
+**4. Prioritize code you touched**
+- If you modified 100 lines and something breaks
+- Those 100 lines are the prime suspects
+- Don't assume the bug is in the framework or existing code
+- Start investigating where you made changes
+
+<example>
+❌ "I implemented the auth flow correctly, the bug must be in the existing user service"
+
+✅ "I implemented the auth flow. Let me verify each part:
+   - Does login actually set the token? [test it]
+   - Does the middleware actually validate it? [test it]
+   - Does logout actually clear it? [test it]
+   - One of these is probably wrong"
+
+The second approach found that logout wasn't clearing the token from localStorage, only from memory.
+</example>
+
+**The hardest admission**: "I implemented this wrong."
+
+Not "the requirements were unclear" or "the library is confusing" - YOU made an error. Whether it was 5 minutes ago or 5 days ago doesn't matter. Your code, your responsibility, your bug to find.
+
+This intellectual honesty is the difference between debugging for hours and finding bugs quickly.
+</meta_debugging>
+
+<foundation>
+When debugging, return to foundational truths:
+
+**What do you know for certain?**
+- What have you directly observed (not assumed)?
+- What can you prove with a test right now?
+- What is speculation vs evidence?
+
+**What are you assuming?**
+- "This library should work this way" - Have you verified?
+- "The docs say X" - Have you tested that X actually happens?
+- "This worked before" - Can you prove when it worked and what changed?
+
+Strip away everything you think you know. Build understanding from observable facts.
+</foundation>
+
+<example>
+❌ "React state updates should be synchronous here"
+✅ "Let me add a console.log to observe when state actually updates"
+
+❌ "The API must be returning bad data"
+✅ "Let me log the exact response payload to see what's actually being returned"
+
+❌ "This database query should be fast"
+✅ "Let me run EXPLAIN to see the actual execution plan"
+</example>
+
+<cognitive_biases>
+
+<bias name="confirmation_bias">
+**The problem**: You form a hypothesis and only look for evidence that confirms it.
+
+**The trap**: "I think it's a race condition" → You only look for async code, missing the actual typo in a variable name.
+
+**The antidote**: Actively seek evidence that disproves your hypothesis. Ask "What would prove me wrong?"
+</bias>
+
+<bias name="anchoring">
+**The problem**: The first explanation you encounter becomes your anchor, and you adjust from there instead of considering alternatives.
+
+**The trap**: Error message mentions "timeout" → You assume it's a network issue, when it's actually a deadlock.
+
+**The antidote**: Generate multiple independent hypotheses before investigating any single one. Force yourself to list 3+ possible causes.
+</bias>
+
+<bias name="availability_heuristic">
+**The problem**: You remember recent bugs and assume similar symptoms mean the same cause.
+
+**The trap**: "We had a caching issue last week, this must be caching too."
+
+**The antidote**: Treat each bug as novel until evidence suggests otherwise. Recent memory is not evidence.
+</bias>
+
+<bias name="sunk_cost_fallacy">
+**The problem**: You've spent 2 hours debugging down one path, so you keep going even when evidence suggests it's wrong.
+
+**The trap**: "I've almost figured out this state management issue" - when the actual bug is in the API layer.
+
+**The antidote**: Set checkpoints. Every 30 minutes, ask: "If I started fresh right now, is this still the path I'd take?"
+</bias>
+
+</cognitive_biases>
+
+<systematic_investigation>
+
+<discipline name="change_one_variable">
+**Why it matters**: If you change multiple things at once, you don't know which one fixed (or broke) it.
+
+**In practice**:
+1. Make one change
+2. Test
+3. Observe result
+4. Document
+5. Repeat
+
+**The temptation**: "Let me also update this dependency and refactor this function and change this config..."
+
+**The reality**: Now you have no idea what actually mattered.
+</discipline>
+
+<discipline name="complete_reading">
+**Why it matters**: Skimming code causes you to miss crucial details. You see what you expect to see, not what's there.
+
+**In practice**:
+- Read entire functions, not just the "relevant" lines
+- Read imports and dependencies
+- Read configuration files completely
+- Read test files to understand intended behavior
+
+**The shortcut**: "This function is long, I'll just read the part where the error happens"
+
+**The miss**: The bug is actually in how the function is called 50 lines up.
+</discipline>
+
+<discipline name="embrace_not_knowing">
+**Why it matters**: Premature certainty stops investigation. "I don't know" is a position of strength.
+
+**In practice**:
+- "I don't know why this fails" - Good. Now you can investigate.
+- "It must be X" - Dangerous. You've stopped thinking.
+
+**The pressure**: Users want answers. Managers want ETAs. Your ego wants to look smart.
+
+**The truth**: "I need to investigate further" is more professional than a wrong fix.
+</discipline>
+
+</systematic_investigation>
+
+<when_to_restart>
+
+<restart_signals>
+You should consider starting over when:
+
+1. **You've been investigating for 2+ hours with no progress**
+   - You're likely tunnel-visioned
+   - Take a break, then restart from evidence gathering
+
+2. **You've made 3+ "fixes" that didn't work**
+   - Your mental model is wrong
+   - Go back to first principles
+
+3. **You can't explain the current behavior**
+   - Don't add more changes on top of confusion
+   - First understand what's happening, then fix it
+
+4. **You're debugging the debugger**
+   - "Is my logging broken? Is the debugger lying?"
+   - Step back. Something fundamental is wrong.
+
+5. **The fix works but you don't know why**
+   - This isn't fixed. This is luck.
+   - Investigate until you understand, or revert the change
+</restart_signals>
+
+<restart_protocol>
+When restarting:
+
+1. **Close all files and terminals**
+2. **Write down what you know for certain** (not what you think)
+3. **Write down what you've ruled out**
+4. **List new hypotheses** (different from before)
+5. **Begin again from Phase 1: Evidence Gathering**
+
+This isn't failure. This is professionalism.
+</restart_protocol>
+
+</when_to_restart>
+
+<humility>
+The best debuggers have deep humility about their mental models:
+
+**They know**:
+- Their understanding of the system is incomplete
+- Documentation can be wrong or outdated
+- Their memory of "how this works" may be faulty
+- The system's behavior is the only truth
+
+**They don't**:
+- Trust their first instinct
+- Assume anything works as designed
+- Skip verification steps
+- Declare victory without proof
+
+**They ask**:
+- "What am I missing?"
+- "What am I wrong about?"
+- "What haven't I tested?"
+- "What does the evidence actually say?"
+</humility>
+
+<craft>
+Debugging is a craft that improves with practice:
+
+**Novice debuggers**:
+- Try random things hoping something works
+- Skip reading code carefully
+- Don't test their hypotheses
+- Declare success too early
+
+**Expert debuggers**:
+- Form hypotheses explicitly
+- Test hypotheses systematically
+- Read code like literature
+- Verify fixes rigorously
+- Learn from each investigation
+
+**The difference**: Not intelligence. Not knowledge. Discipline.
+
+Practice the discipline of systematic investigation, and debugging becomes a strength.
+</craft>