@tuan_son.dinh/gsd 2.6.0

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>

package/src/resources/skills/debug-like-expert/references/hypothesis-testing.md

@@ -0,0 +1,373 @@
+
+<overview>
+Debugging is applied scientific method. You observe a phenomenon (the bug), form hypotheses about its cause, design experiments to test those hypotheses, and revise based on evidence. This isn't metaphorical - it's literal experimental science.
+</overview>
+
+
+<principle name="falsifiability">
+A good hypothesis can be proven wrong. If you can't design an experiment that could disprove it, it's not a useful hypothesis.
+
+**Bad hypotheses** (unfalsifiable):
+- "Something is wrong with the state"
+- "The timing is off"
+- "There's a race condition somewhere"
+- "The library is buggy"
+
+**Good hypotheses** (falsifiable):
+- "The user state is being reset because the component remounts when the route changes"
+- "The API call completes after the component unmounts, causing the state update on unmounted component warning"
+- "Two async operations are modifying the same array without locking, causing data loss"
+- "The library's caching mechanism is returning stale data because our cache key doesn't include the timestamp"
+
+**The difference**: Specificity. Good hypotheses make specific, testable claims.
+</principle>
+
+<how_to_form>
+**Process for forming hypotheses**:
+
+1. **Observe the behavior precisely**
+   - Not "it's broken"
+   - But "the counter shows 3 when clicking once, should show 1"
+
+2. **Ask "What could cause this?"**
+   - List every possible cause you can think of
+   - Don't judge them yet, just brainstorm
+
+3. **Make each hypothesis specific**
+   - Not "state is wrong"
+   - But "state is being updated twice because handleClick is called twice"
+
+4. **Identify what evidence would support/refute each**
+   - If hypothesis X is true, I should see Y
+   - If hypothesis X is false, I should see Z
+
+<example>
+**Observation**: Button click sometimes saves data, sometimes doesn't.
+
+**Vague hypothesis**: "The save isn't working reliably"
+❌ Unfalsifiable, not specific
+
+**Specific hypotheses**:
+1. "The save API call is timing out when network is slow"
+   - Testable: Check network tab for timeout errors
+   - Falsifiable: If all requests complete successfully, this is wrong
+
+2. "The save button is being double-clicked, and the second request overwrites with stale data"
+   - Testable: Add logging to count clicks
+   - Falsifiable: If only one click is registered, this is wrong
+
+3. "The save is successful but the UI doesn't update because the response is being ignored"
+   - Testable: Check if API returns success
+   - Falsifiable: If UI updates on successful response, this is wrong
+</example>
+</how_to_form>
+
+
+<experimental_design>
+An experiment is a test that produces evidence supporting or refuting a hypothesis.
+
+**Good experiments**:
+- Test one hypothesis at a time
+- Have clear success/failure criteria
+- Produce unambiguous results
+- Are repeatable
+
+**Bad experiments**:
+- Test multiple things at once
+- Have unclear outcomes ("maybe it works better?")
+- Rely on subjective judgment
+- Can't be reproduced
+
+<framework>
+For each hypothesis, design an experiment:
+
+**1. Prediction**: If hypothesis H is true, then I will observe X
+**2. Test setup**: What do I need to do to test this?
+**3. Measurement**: What exactly am I measuring?
+**4. Success criteria**: What result confirms H? What result refutes H?
+**5. Run the experiment**: Execute the test
+**6. Observe the result**: Record what actually happened
+**7. Conclude**: Does this support or refute H?
+
+</framework>
+
+<example>
+**Hypothesis**: "The component is re-rendering excessively because the parent is passing a new object reference on every render"
+
+**1. Prediction**: If true, the component will re-render even when the object's values haven't changed
+
+**2. Test setup**:
+   - Add console.log in component body to count renders
+   - Add console.log in parent to track when object is created
+   - Add useEffect with the object as dependency to log when it changes
+
+**3. Measurement**: Count of renders and object creations
+
+**4. Success criteria**:
+   - Confirms H: Component re-renders match parent renders, object reference changes each time
+   - Refutes H: Component only re-renders when object values actually change
+
+**5. Run**: Execute the code with logging
+
+**6. Observe**:
+   ```
+   [Parent] Created user object
+   [Child] Rendering (1)
+   [Parent] Created user object
+   [Child] Rendering (2)
+   [Parent] Created user object
+   [Child] Rendering (3)
+   ```
+
+**7. Conclude**: CONFIRMED. New object every parent render → child re-renders
+</example>
+</experimental_design>
+
+
+<evidence_quality>
+Not all evidence is equal. Learn to distinguish strong from weak evidence.
+
+**Strong evidence**:
+- Directly observable ("I can see in the logs that X happens")
+- Repeatable ("This fails every time I do Y")
+- Unambiguous ("The value is definitely null, not undefined")
+- Independent ("This happens even in a fresh browser with no cache")
+
+**Weak evidence**:
+- Hearsay ("I think I saw this fail once")
+- Non-repeatable ("It failed that one time but I can't reproduce it")
+- Ambiguous ("Something seems off")
+- Confounded ("It works after I restarted the server and cleared the cache and updated the package")
+
+<examples>
+**Strong**:
+```javascript
+console.log('User ID:', userId); // Output: User ID: undefined
+console.log('Type:', typeof userId); // Output: Type: undefined
+```
+✅ Direct observation, unambiguous
+
+**Weak**:
+"I think the user ID might not be set correctly sometimes"
+❌ Vague, not verified, uncertain
+
+**Strong**:
+```javascript
+for (let i = 0; i < 100; i++) {
+  const result = processData(testData);
+  if (result !== expected) {
+    console.log('Failed on iteration', i);
+  }
+}
+// Output: Failed on iterations: 3, 7, 12, 23, 31...
+```
+✅ Repeatable, shows pattern
+
+**Weak**:
+"It usually works, but sometimes fails"
+❌ Not quantified, no pattern identified
+</examples>
+</evidence_quality>
+
+
+<decision_point>
+Don't act too early (premature fix) or too late (analysis paralysis).
+
+**Act when you can answer YES to all**:
+
+1. **Do you understand the mechanism?**
+   - Not just "what fails" but "why it fails"
+   - Can you explain the chain of events that produces the bug?
+
+2. **Can you reproduce it reliably?**
+   - Either always reproduces, or you understand the conditions that trigger it
+   - If you can't reproduce, you don't understand it yet
+
+3. **Do you have evidence, not just theory?**
+   - You've observed the behavior directly
+   - You've logged the values, traced the execution
+   - You're not guessing
+
+4. **Have you ruled out alternatives?**
+   - You've considered other hypotheses
+   - Evidence contradicts the alternatives
+   - This is the most likely cause, not just the first idea
+
+**Don't act if**:
+- "I think it might be X" - Too uncertain
+- "This could be the issue" - Not confident enough
+- "Let me try changing Y and see" - Random changes, not hypothesis-driven
+- "I'll fix it and if it works, great" - Outcome-based, not understanding-based
+
+<example>
+**Too early** (don't act):
+- Hypothesis: "Maybe the API is slow"
+- Evidence: None, just a guess
+- Action: Add caching
+- Result: Bug persists, now you have caching to debug too
+
+**Right time** (act):
+- Hypothesis: "API response is missing the 'status' field when user is inactive, causing the app to crash"
+- Evidence:
+  - Logged API response for active user: has 'status' field
+  - Logged API response for inactive user: missing 'status' field
+  - Logged app behavior: crashes on accessing undefined status
+- Action: Add defensive check for missing status field
+- Result: Bug fixed because you understood the cause
+</example>
+</decision_point>
+
+
+<recovery>
+You will be wrong sometimes. This is normal. The skill is recovering gracefully.
+
+**When your hypothesis is disproven**:
+
+1. **Acknowledge it explicitly**
+   - "This hypothesis was wrong because [evidence]"
+   - Don't gloss over it or rationalize
+   - Intellectual honesty with yourself
+
+2. **Extract the learning**
+   - What did this experiment teach you?
+   - What did you rule out?
+   - What new information do you have?
+
+3. **Revise your understanding**
+   - Update your mental model
+   - What does the evidence actually suggest?
+
+4. **Form new hypotheses**
+   - Based on what you now know
+   - Avoid just moving to "second-guess" - use the evidence
+
+5. **Don't get attached to hypotheses**
+   - You're not your ideas
+   - Being wrong quickly is better than being wrong slowly
+
+<example>
+**Initial hypothesis**: "The memory leak is caused by event listeners not being cleaned up"
+
+**Experiment**: Check Chrome DevTools for listener counts
+**Result**: Listener count stays stable, doesn't grow over time
+
+**Recovery**:
+1. ✅ "Event listeners are NOT the cause. The count doesn't increase."
+2. ✅ "I've ruled out event listeners as the culprit"
+3. ✅ "But the memory profile shows objects accumulating. What objects? Let me check the heap snapshot..."
+4. ✅ "New hypothesis: Large arrays are being cached and never released. Let me test by checking the heap for array sizes..."
+
+This is good debugging. Wrong hypothesis, quick recovery, better understanding.
+</example>
+</recovery>
+
+
+<multiple_hypotheses>
+Don't fall in love with your first hypothesis. Generate multiple alternatives.
+
+**Strategy**: "Strong inference" - Design experiments that differentiate between competing hypotheses.
+
+<example>
+**Problem**: Form submission fails intermittently
+
+**Competing hypotheses**:
+1. Network timeout
+2. Validation failure
+3. Race condition with auto-save
+4. Server-side rate limiting
+
+**Design experiment that differentiates**:
+
+Add logging at each stage:
+```javascript
+try {
+  console.log('[1] Starting validation');
+  const validation = await validate(formData);
+  console.log('[1] Validation passed:', validation);
+
+  console.log('[2] Starting submission');
+  const response = await api.submit(formData);
+  console.log('[2] Response received:', response.status);
+
+  console.log('[3] Updating UI');
+  updateUI(response);
+  console.log('[3] Complete');
+} catch (error) {
+  console.log('[ERROR] Failed at stage:', error);
+}
+```
+
+**Observe results**:
+- Fails at [2] with timeout error → Hypothesis 1
+- Fails at [1] with validation error → Hypothesis 2
+- Succeeds but [3] has wrong data → Hypothesis 3
+- Fails at [2] with 429 status → Hypothesis 4
+
+**One experiment, differentiates between four hypotheses.**
+</example>
+</multiple_hypotheses>
+
+
+<workflow>
+```
+1. Observe unexpected behavior
+     ↓
+2. Form specific hypotheses (plural)
+     ↓
+3. For each hypothesis: What would prove/disprove?
+     ↓
+4. Design experiment to test
+     ↓
+5. Run experiment
+     ↓
+6. Observe results
+     ↓
+7. Evaluate: Confirmed, refuted, or inconclusive?
+     ↓
+8a. If CONFIRMED → Design fix based on understanding
+8b. If REFUTED → Return to step 2 with new hypotheses
+8c. If INCONCLUSIVE → Redesign experiment or gather more data
+```
+
+**Key insight**: This is a loop, not a line. You'll cycle through multiple times. That's expected.
+</workflow>
+
+
+<pitfalls>
+
+**Pitfall: Testing multiple hypotheses at once**
+- You change three things and it works
+- Which one fixed it? You don't know
+- Solution: Test one hypothesis at a time
+
+**Pitfall: Confirmation bias in experiments**
+- You only look for evidence that confirms your hypothesis
+- You ignore evidence that contradicts it
+- Solution: Actively seek disconfirming evidence
+
+**Pitfall: Acting on weak evidence**
+- "It seems like maybe this could be..."
+- Solution: Wait for strong, unambiguous evidence
+
+**Pitfall: Not documenting results**
+- You forget what you tested
+- You repeat the same experiments
+- Solution: Write down each hypothesis and its result
+
+**Pitfall: Giving up on the scientific method**
+- Under pressure, you start making random changes
+- "Let me just try this..."
+- Solution: Double down on rigor when pressure increases
+</pitfalls>
+
+<excellence>
+**Great debuggers**:
+- Form multiple competing hypotheses
+- Design clever experiments that differentiate between them
+- Follow the evidence wherever it leads
+- Revise their beliefs when proven wrong
+- Act only when they have strong evidence
+- Understand the mechanism, not just the symptom
+
+This is the difference between guessing and debugging.
+</excellence>