Initial commit
This commit is contained in:
Zhongwei Li
43
skills/debugging/reference/antipatterns.md
Normal file
43
skills/debugging/reference/antipatterns.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Debugging Antipatterns (and Recoveries)
|
||||
|
||||
Avoid these documented failure modes; use the recovery steps when detected.
|
||||
|
||||
## 1) Circular Reasoning Without Learning
|
||||
- Symptom: Proposing the same fix repeatedly
|
||||
- Recovery: Stop and use `SequentialThinking:process_thought` to analyze why the fix failed; propose a substantively different approach
|
||||
|
||||
## 2) Premature Victory Declaration
|
||||
- Symptom: Declaring success without changes/tests
|
||||
- Recovery: Show changed lines; run tests that fail-before/pass-after; verify across scenarios
|
||||
|
||||
## 3) Pattern Amnesia
|
||||
- Symptom: Ignoring established code patterns/conventions
|
||||
- Recovery: `codebase_search` similar implementations; extract and follow patterns; explain any deviation
|
||||
|
||||
## 4) Implementation Before Understanding
|
||||
- Symptom: Jumping to code edits without examining context
|
||||
- Recovery: Explore → Plan → Code; read relevant files; outline plan; then implement
|
||||
|
||||
## 5) Context-Limited Fixes
|
||||
- Symptom: Fixing one location only
|
||||
- Recovery: Search project-wide (grep/codebase_search) for the root pattern; patch all occurrences; refactor if repeated
|
||||
|
||||
## 6) Symptom Chasing
|
||||
- Symptom: Treating error messages as the problem
|
||||
- Recovery: Apply 5 Whys; confirm root cause explains all symptoms; then fix
|
||||
|
||||
## 7) Assumption-Based Debugging
|
||||
- Symptom: Assuming library/system behavior
|
||||
- Recovery: Research via Firecrawl:search; verify with `Context7:get-library-docs`; test assumptions
|
||||
|
||||
## 8) Context Overload Ignorance
|
||||
- Symptom: Degraded reasoning in long sessions
|
||||
- Recovery: Restart at ~50%; carry summary of facts, hypothesis, next step only
|
||||
|
||||
## 9) Tool Misuse
|
||||
- Symptom: Using wrong tool for task
|
||||
- Recovery: Decision tree: exact text→grep; concept→codebase_search; full context→read_file; research→Firecrawl/Perplexity; complex analysis→SequentialThinking
|
||||
|
||||
## 10) Plan Abandonment
|
||||
- Symptom: Ignoring the plan mid-way
|
||||
- Recovery: Note deviation; justify; update plan; resume at correct step
|
||||
135
skills/debugging/reference/root-cause-framework.md
Normal file
135
skills/debugging/reference/root-cause-framework.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# Root Cause Analysis Framework
|
||||
|
||||
Advanced techniques for identifying fundamental causes rather than symptoms.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [The 5 Whys (Applied to Code)](#the-5-whys-applied-to-code)
|
||||
- [Architectural Analysis Method](#architectural-analysis-method)
|
||||
- [Data Flow Tracing](#data-flow-tracing)
|
||||
- [State Analysis Patterns](#state-analysis-patterns)
|
||||
- [Integration Point Analysis](#integration-point-analysis)
|
||||
- [Dependency Chain Analysis](#dependency-chain-analysis)
|
||||
- [Performance Root Cause Analysis](#performance-root-cause-analysis)
|
||||
- [Sequential Thinking Templates](#sequential-thinking-templates)
|
||||
|
||||
## The 5 Whys (Applied to Code)
|
||||
|
||||
Ask "why" iteratively to drill down from symptom to root cause.
|
||||
|
||||
### Example: Null Pointer Exception
|
||||
|
||||
1. Why does the null pointer exception occur?
|
||||
→ `user.getEmail()` is called on a null user object
|
||||
2. Why is the user object null?
|
||||
→ `findUserById()` returns null when no user is found
|
||||
3. Why does `findUserById()` return null instead of throwing?
|
||||
→ Original design used null to indicate "not found"
|
||||
4. Why wasn't this caught earlier in the call chain?
|
||||
→ Calling code doesn't check for null before using the user
|
||||
5. Why doesn't the calling code check for null?
|
||||
→ API contract is ambiguous about null as a valid return value
|
||||
|
||||
Root cause: Ambiguous API contract leads to inconsistent null handling.
|
||||
Proper fix: Define and enforce a clear API contract (Optional/exception/documented null).
|
||||
|
||||
## Architectural Analysis Method
|
||||
|
||||
When bugs suggest deeper design issues, analyze architecture systematically.
|
||||
|
||||
1. Map components: interactions, data flows, boundaries
|
||||
2. Identify assumptions (inputs, state, timing, external systems)
|
||||
3. Find assumption mismatches between components
|
||||
4. Choose architectural fix over workaround when systemic
|
||||
|
||||
Use `codebase_search` prompts like:
|
||||
- "How does ComponentA communicate with ComponentB?"
|
||||
- "What data flows from Source to Destination?"
|
||||
|
||||
## Data Flow Tracing
|
||||
|
||||
Trace transformations to locate where data goes wrong.
|
||||
|
||||
- Backward tracing: start at observation point → immediate source → transformation → origin
|
||||
- Forward tracing: origin → each transformation → final state
|
||||
- At each step compare expected vs actual state
|
||||
|
||||
Common root causes:
|
||||
- Missing validation
|
||||
- Incorrect transformation logic
|
||||
- Lost context/metadata
|
||||
- Race conditions
|
||||
- Type/encoding mismatch
|
||||
|
||||
## State Analysis Patterns
|
||||
|
||||
Investigate state transitions and invariants.
|
||||
|
||||
- Uninitialized state: used before proper setup
|
||||
- Stale state: cache invalidation/refresh failures
|
||||
- Inconsistent state: related data out of sync (needs atomicity)
|
||||
- Invalid state: invariants not enforced (add validation/assertions)
|
||||
- Concurrent corruption: missing synchronization/immutability
|
||||
|
||||
## Integration Point Analysis
|
||||
|
||||
Verify integration contracts at boundaries.
|
||||
|
||||
- Data format: actual vs expected
|
||||
- Protocol/version: compatibility and usage
|
||||
- Timing: sync vs async, timeouts, ordering
|
||||
- Error handling: propagation and retries
|
||||
- AuthZ/AuthN: credentials, validation, failure behavior
|
||||
|
||||
Root cause patterns:
|
||||
- Mismatched versions
|
||||
- Incomplete error handling
|
||||
- Configuration mismatch
|
||||
- Network constraints
|
||||
|
||||
## Dependency Chain Analysis
|
||||
|
||||
Map direct, transitive, and hidden dependencies.
|
||||
|
||||
- Version conflicts (multiple versions)
|
||||
- Missing dependencies (runtime load failures)
|
||||
- Initialization order issues
|
||||
- Circular dependencies
|
||||
|
||||
Use `codebase_search`:
|
||||
- "What imports/uses ComponentX?"
|
||||
- "What does ComponentX depend on?"
|
||||
|
||||
## Performance Root Cause Analysis
|
||||
|
||||
Identify bottlenecks systematically.
|
||||
|
||||
1. Measure first (profile under realistic load)
|
||||
2. Check algorithmic complexity and hotspots
|
||||
3. Analyze resource usage (CPU, memory, I/O, network)
|
||||
4. Classify cause: algorithm, implementation, contention, external
|
||||
|
||||
Fix strategies:
|
||||
- Algorithmic improvements
|
||||
- Caching/batching
|
||||
- Lazy loading
|
||||
- Parallelization/asynchronous I/O
|
||||
|
||||
## Sequential Thinking Templates
|
||||
|
||||
Use `SequentialThinking:process_thought` to structure complex analysis.
|
||||
|
||||
Thought 1 - Problem Definition
|
||||
- Symptom, context, confirmed facts, unknowns
|
||||
|
||||
Thought 2 - Hypotheses
|
||||
- 3–5 candidates, assumptions, likelihood ranking
|
||||
|
||||
Thought 3 - Evidence
|
||||
- For/against each hypothesis; challenge assumptions
|
||||
|
||||
Thought 4 - Selection
|
||||
- Pick most likely; rationale; confidence
|
||||
|
||||
Thought 5 - Verification
|
||||
- Predictions, test plan, alternatives if wrong
|
||||
Reference in New Issue
Block a user