mirror of
https://github.com/duthaho/claudekit.git
synced 2026-09-07 10:40:52 +03:00
feat: adding new skills, including testing patterns and methodologies, along with bundled resources for better usability.
This commit is contained in:
duthaho
@@ -1,9 +1,11 @@
|
||||
---
|
||||
name: root-cause-tracing
|
||||
description: >
|
||||
Trigger this skill whenever a bug manifests far from its origin, when stack traces show multiple layers of indirection, or when data corruption appears with no obvious source. Use for any scenario involving "it was already wrong by the time it got here," deep execution stack errors, constraint violations caused by upstream failures, or mysterious data state issues. Always prefer this over surface-level fixes when the error location differs from the bug location.
|
||||
---
|
||||
|
||||
# Root Cause Tracing
|
||||
|
||||
## Description
|
||||
|
||||
Debugging technique for bugs that manifest deep in execution stacks. Systematically trace backward through the call chain to identify the original trigger, rather than fixing symptoms at the point of failure.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Errors occur far from entry points
|
||||
@@ -12,6 +14,12 @@ Debugging technique for bugs that manifest deep in execution stacks. Systematica
|
||||
- Stack traces show multiple levels of indirection
|
||||
- "It was already wrong by the time it got here"
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Surface-level UI bugs where the cause and effect are co-located
|
||||
- Known issues with documented fixes already available in the codebase or issue tracker
|
||||
- Performance optimization work where profiling tools are more appropriate than tracing
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
@@ -228,3 +236,9 @@ Fixing at the source:
|
||||
- [ ] Test proves fix works
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `methodology/systematic-debugging` - General debugging methodology; use root-cause-tracing when the bug location differs from the error location
|
||||
- `methodology/defense-in-depth` - After tracing the root cause, apply multi-layer validation to make the bug structurally impossible
|
||||
- `methodology/sequential-thinking` - Use sequential thinking to systematically document evidence and hypotheses during complex tracing sessions
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
# Tracing Techniques Reference
|
||||
|
||||
Backward-tracing techniques for systematic root cause analysis.
|
||||
|
||||
## Stack Trace Analysis
|
||||
|
||||
### Reading a Stack Trace
|
||||
|
||||
1. Start at the **bottom** (most recent call) to find the immediate failure
|
||||
2. Scan **upward** to find the first frame in **your code** (not library code)
|
||||
3. That frame is usually the symptom location, not the cause
|
||||
4. Continue upward to find where bad data or state originated
|
||||
|
||||
### Symptom vs Cause
|
||||
|
||||
| What You See | Likely Actual Cause |
|
||||
|---|---|
|
||||
| `NullPointerException` / `TypeError: cannot read property of undefined` | Value not set upstream, missing null check at origin |
|
||||
| `IndexOutOfBoundsException` | Off-by-one in loop logic or empty collection not guarded |
|
||||
| `ConnectionRefusedError` | Service down, wrong port, firewall rule, DNS resolution |
|
||||
| `TimeoutError` | Deadlock, resource exhaustion, slow query, network partition |
|
||||
| `ValidationError` | Caller passing wrong shape, schema mismatch, migration gap |
|
||||
|
||||
### Tips
|
||||
|
||||
- Filter out framework frames to reduce noise
|
||||
- In async code, the stack may be split; look for `caused by` or `previous` sections
|
||||
- In Python, read `__cause__` and `__context__` on chained exceptions
|
||||
- In TypeScript/Node, check `error.cause` (ES2022+)
|
||||
|
||||
## Binary Search / Git Bisect
|
||||
|
||||
### When to Use
|
||||
|
||||
- Bug exists now but worked at some known-good point
|
||||
- Reproducer is automatable (script, test command)
|
||||
|
||||
### Process
|
||||
|
||||
```bash
|
||||
git bisect start
|
||||
git bisect bad # current commit is broken
|
||||
git bisect good <known-good-sha> # last known working commit
|
||||
# Git checks out a midpoint; run your test
|
||||
git bisect good # or bad, based on result
|
||||
# Repeat until Git identifies the first bad commit
|
||||
git bisect reset # return to original branch
|
||||
```
|
||||
|
||||
### Automated Bisect
|
||||
|
||||
```bash
|
||||
git bisect start HEAD <good-sha>
|
||||
git bisect run ./test-script.sh
|
||||
# Exit 0 = good, exit 1 = bad, exit 125 = skip
|
||||
```
|
||||
|
||||
## Log Correlation
|
||||
|
||||
### Technique
|
||||
|
||||
1. Identify the **exact timestamp** of the error
|
||||
2. Search all related service logs within a window (e.g., +/- 30 seconds)
|
||||
3. Filter by **correlation ID**, **request ID**, or **user ID** across services
|
||||
4. Build a timeline of events across services
|
||||
|
||||
### Correlation Fields to Look For
|
||||
|
||||
- `request_id` or `trace_id` (distributed tracing)
|
||||
- `user_id` or `session_id`
|
||||
- Source IP or client identifier
|
||||
- Timestamps (normalize to UTC)
|
||||
|
||||
### Tools
|
||||
|
||||
- `grep` / `rg` with timestamp ranges
|
||||
- Structured logging with JSON output + `jq`
|
||||
- Distributed tracing (OpenTelemetry, Jaeger, Zipkin)
|
||||
|
||||
## Dependency Analysis (Backward Data Flow)
|
||||
|
||||
### Process
|
||||
|
||||
1. Start at the error location
|
||||
2. Identify the **variable or value** that is wrong
|
||||
3. Trace backward: where was this value set?
|
||||
4. At each step, ask: is this value correct here? If yes, move forward. If no, keep going back.
|
||||
5. The root cause is where correct data first becomes incorrect.
|
||||
|
||||
### Common Data Flow Points
|
||||
|
||||
```
|
||||
User Input -> Validation -> Transform -> Business Logic -> Persistence -> Query -> Response
|
||||
```
|
||||
|
||||
Trace backward through this chain from wherever the error manifests.
|
||||
|
||||
### Dependency Categories
|
||||
|
||||
| Dependency | What to Check |
|
||||
|---|---|
|
||||
| Function arguments | Caller passing wrong values |
|
||||
| Config / env vars | Wrong environment, stale config |
|
||||
| Database state | Missing migration, corrupt data |
|
||||
| External API | Changed response format, auth expiry |
|
||||
| Shared state | Race condition, stale cache |
|
||||
|
||||
## Instrumentation Points
|
||||
|
||||
### Where to Add Temporary Logging
|
||||
|
||||
1. **Entry/exit of suspected function** — log arguments and return value
|
||||
2. **Before/after external calls** — log request and response
|
||||
3. **Branch points** — log which path was taken and why
|
||||
4. **Data transformation steps** — log before and after
|
||||
5. **Error handlers** — log the full error with context
|
||||
|
||||
### Guidelines
|
||||
|
||||
- Use a distinct prefix (e.g., `[DEBUG-TRACE]`) so logs are easy to find and remove
|
||||
- Log the **type** as well as the **value** (catches `"null"` vs `null`)
|
||||
- In production, use feature flags or debug log levels, not code changes
|
||||
- Remove all temporary logging before committing
|
||||
|
||||
### Python Example
|
||||
|
||||
```python
|
||||
import logging
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
def process_order(order_id: str) -> Order:
|
||||
logger.debug("[DEBUG-TRACE] process_order called with: %s (type: %s)", order_id, type(order_id))
|
||||
order = db.get_order(order_id)
|
||||
logger.debug("[DEBUG-TRACE] db.get_order returned: %s", order)
|
||||
# ... rest of logic
|
||||
```
|
||||
|
||||
### TypeScript Example
|
||||
|
||||
```typescript
|
||||
function processOrder(orderId: string): Order {
|
||||
console.debug(`[DEBUG-TRACE] processOrder called with: ${orderId} (type: ${typeof orderId})`);
|
||||
const order = db.getOrder(orderId);
|
||||
console.debug(`[DEBUG-TRACE] db.getOrder returned:`, order);
|
||||
// ... rest of logic
|
||||
}
|
||||
```
|
||||
|
||||
## Common Root Cause Categories
|
||||
|
||||
| Category | Symptoms | Investigation Approach |
|
||||
|---|---|---|
|
||||
| **Data issues** | Wrong output, validation errors, corrupt state | Trace the bad value backward through the data flow |
|
||||
| **Race conditions** | Intermittent failures, works-on-retry, order-dependent | Look for shared mutable state, add timing logs, test with delays |
|
||||
| **Config drift** | Works locally but not in staging/prod | Diff environment configs, check env vars, verify secrets |
|
||||
| **Dependency changes** | Broke after deploy with no code changes | Check lock file diffs, dependency changelogs, API version headers |
|
||||
| **Resource exhaustion** | Timeouts, OOM, connection pool errors | Monitor metrics (memory, CPU, connections, disk), check for leaks |
|
||||
| **Schema mismatch** | Serialization errors, missing fields | Compare expected vs actual schema, check migration status |
|
||||
|
||||
## Quick Decision: Which Technique to Use
|
||||
|
||||
| Situation | Start With |
|
||||
|---|---|
|
||||
| Have a stack trace | Stack trace analysis |
|
||||
| "It used to work" | Git bisect |
|
||||
| Multi-service issue | Log correlation |
|
||||
| Wrong data in output | Backward data flow |
|
||||
| No idea where to start | Add instrumentation at boundaries |
|
||||
Reference in New Issue
Block a user