developer-ai 1.0.0

package/skills/debugging/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: debugging
+description: Systematic approach to debugging code issues. Use when encountering bugs, errors, unexpected behavior, or crashes. Covers debugging strategies, tools, common bug patterns, and step-by-step approaches for isolating and fixing issues.
+---
+
+# Debugging Skill
+
+This skill provides systematic approaches to identifying and fixing bugs efficiently.
+
+## Overview
+
+Debugging is a systematic process of finding and resolving issues. This skill teaches methodical approaches that work across different types of bugs and technologies.
+
+## The Debugging Mindset
+
+### Core Principles
+1. **Understand the expected behavior** - What should happen?
+2. **Understand the actual behavior** - What is happening?
+3. **Form hypotheses** - What could cause the difference?
+4. **Test hypotheses** - Verify or eliminate each possibility
+5. **Fix and verify** - Ensure the fix works without side effects
+
+## Systematic Debugging Process
+
+### Step 1: Reproduce the Bug
+- Get exact steps to reproduce
+- Identify if it's consistent or intermittent
+- Note the environment (browser, OS, versions)
+- Create a minimal reproduction if possible
+
+### Step 2: Gather Information
+- Check error messages carefully
+- Read stack traces
+- Check logs
+- Review recent changes
+- Check if it worked before
+
+### Step 3: Isolate the Problem
+- Use binary search (comment out half the code)
+- Remove components until bug disappears
+- Add them back one by one
+- Find the smallest reproduction
+
+### Step 4: Form Hypotheses
+- List possible causes
+- Rank by likelihood
+- Test most likely first
+
+### Step 5: Fix and Verify
+- Fix the root cause, not symptoms
+- Add tests for the bug
+- Verify fix doesn't break other things
+- Document the fix
+
+## Common Bug Patterns
+
+### JavaScript/TypeScript
+
+**Async/Await Issues**
+```javascript
+// BUG: Forgetting await
+async function fetchData() {
+  const data = fetch('/api/data'); // Missing await!
+  console.log(data); // Logs Promise, not data
+}
+
+// FIX:
+async function fetchData() {
+  const data = await fetch('/api/data');
+  const json = await data.json();
+  console.log(json);
+}
+```
+
+**Reference vs Value**
+```javascript
+// BUG: Modifying original object
+function addProperty(obj) {
+  obj.newProp = 'value'; // Mutates original!
+  return obj;
+}
+
+// FIX: Create a copy
+function addProperty(obj) {
+  return { ...obj, newProp: 'value' };
+}
+```
+
+**Closure Issues**
+```javascript
+// BUG: All buttons alert same number
+for (var i = 0; i < 5; i++) {
+  buttons[i].onclick = function() {
+    alert(i); // Always 5!
+  };
+}
+
+// FIX: Use let or closure
+for (let i = 0; i < 5; i++) {
+  buttons[i].onclick = function() {
+    alert(i); // Correct value
+  };
+}
+```
+
+**This Binding**
+```javascript
+// BUG: Lost 'this' context
+class Handler {
+  value = 42;
+  handleClick() {
+    console.log(this.value); // undefined!
+  }
+}
+button.onclick = handler.handleClick;
+
+// FIX: Bind or arrow function
+button.onclick = handler.handleClick.bind(handler);
+// or
+handleClick = () => {
+  console.log(this.value);
+}
+```
+
+### React Specific
+
+**Stale Closure in useEffect**
+```javascript
+// BUG: Stale count value
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(count + 1); // Always uses initial count!
+  }, 1000);
+  return () => clearInterval(interval);
+}, []); // Empty deps
+
+// FIX: Use functional update
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCount(c => c + 1);
+  }, 1000);
+  return () => clearInterval(interval);
+}, []);
+```
+
+**Infinite Re-renders**
+```javascript
+// BUG: Object in dependency array
+useEffect(() => {
+  // ...
+}, [{ foo: 'bar' }]); // New object every render!
+
+// FIX: Memoize or use primitive
+const config = useMemo(() => ({ foo: 'bar' }), []);
+useEffect(() => {
+  // ...
+}, [config]);
+```
+
+### CSS Issues
+
+**Z-index Problems**
+- Check stacking context (transform, opacity creates new context)
+- Parent z-index limits child
+- Use browser dev tools layers view
+
+**Flexbox/Grid Layout**
+- Check parent has display: flex/grid
+- Verify flex-direction
+- Check for overflow issues
+- Use dev tools flexbox/grid overlay
+
+### Network Issues
+
+**CORS Errors**
+- Check server Access-Control-Allow-Origin headers
+- Verify credentials mode matches server config
+- Check for preflight requirements
+
+**API Errors**
+- Check request format (Content-Type)
+- Verify authentication headers
+- Check payload structure matches API expectations
+
+## Debugging Tools
+
+### Browser DevTools
+
+**Console**
+```javascript
+console.log(variable);           // Basic logging
+console.table(array);            // Tabular view
+console.trace();                 // Stack trace
+console.time('op'); /* code */ console.timeEnd('op'); // Timing
+console.group('name'); /* logs */ console.groupEnd(); // Grouping
+```
+
+**Breakpoints**
+- Line breakpoints
+- Conditional breakpoints
+- Exception breakpoints
+- DOM mutation breakpoints
+- Event listener breakpoints
+- XHR/fetch breakpoints
+
+**Network Tab**
+- Check request/response
+- Verify headers
+- Check timing
+- Throttle connection
+
+**Performance Tab**
+- Record performance
+- Find bottlenecks
+- Check memory usage
+
+### VS Code Debugging
+
+```json
+// launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Current File",
+      "program": "${file}",
+      "skipFiles": ["<node_internals>/**"]
+    }
+  ]
+}
+```
+
+### Logging Strategies
+
+**Structured Logging**
+```javascript
+console.log(JSON.stringify({
+  event: 'user_action',
+  action: 'button_click',
+  userId: user.id,
+  timestamp: Date.now(),
+  context: { page: window.location.pathname }
+}, null, 2));
+```
+
+**Debug Library**
+```javascript
+import debug from 'debug';
+const log = debug('app:module');
+
+log('Processing item %O', item);
+// Enable with: DEBUG=app:* node app.js
+```
+
+## When You're Stuck
+
+### Rubber Duck Debugging
+1. Explain the problem out loud
+2. Walk through the code line by line
+3. Explain what each line should do
+4. Often reveals the issue
+
+### Take a Break
+- Fresh eyes catch more bugs
+- Step away for 15 minutes
+- Work on something else
+
+### Ask for Help
+- Prepare a minimal reproduction
+- Document what you've tried
+- Be specific about the issue
+- Share relevant error messages
+
+### Search Effectively
+- Include error message in quotes
+- Add technology name
+- Try different phrasings
+- Check GitHub issues
+
+## Bug Prevention
+
+### Write Defensive Code
+```javascript
+function processUser(user) {
+  if (!user) {
+    throw new Error('User is required');
+  }
+  if (!user.email) {
+    throw new Error('User email is required');
+  }
+  // Process...
+}
+```
+
+### Use TypeScript
+```typescript
+interface User {
+  id: string;
+  email: string;
+  name?: string;
+}
+
+function processUser(user: User): void {
+  // TypeScript catches type errors at compile time
+}
+```
+
+### Write Tests
+```javascript
+test('processUser throws without user', () => {
+  expect(() => processUser(null)).toThrow('User is required');
+});
+
+test('processUser throws without email', () => {
+  expect(() => processUser({ id: '1' })).toThrow('email is required');
+});
+```
+
+## Debugging Checklist
+
+When debugging:
+- [ ] Can reproduce the bug consistently?
+- [ ] Have exact error message/behavior?
+- [ ] Know when it started happening?
+- [ ] Checked recent changes?
+- [ ] Isolated to specific component?
+- [ ] Tested hypotheses systematically?
+- [ ] Fixed root cause (not symptom)?
+- [ ] Added test to prevent regression?
+- [ ] Verified fix in production-like environment?