📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,222 @@
+# Documentation Templates
+
+Templates for investigation logging and root cause reports.
+
+## Investigation Log
+
+Real-time documentation during investigation.
+
+### Format
+
+```
+[TIMESTAMP] STAGE: Action → Result
+
+[10:15] DISCOVERY: Gathered error logs → Found NullPointerException in UserService
+[10:22] HYPOTHESIS: Suspect user object not initialized when accessed
+[10:28] TEST: Added null check logging → Confirmed user is null
+[10:35] EVIDENCE: Traced call path → findById returning null for valid ID
+[10:42] HYPOTHESIS: Database connection issue
+[10:48] TEST: Direct DB query → Returns data correctly
+[10:52] HYPOTHESIS: Caching returning stale null
+[10:58] TEST: Disabled cache → Issue resolved
+[11:05] ROOT CAUSE: Cache not invalidated on user update
+```
+
+### Entry Types
+
+| Prefix | Use For |
+|--------|---------|
+| DISCOVERY | New information gathered |
+| HYPOTHESIS | New theory formed |
+| TEST | Experiment executed |
+| EVIDENCE | Data that supports/refutes hypothesis |
+| ROOT CAUSE | Final determination |
+| BLOCKED | Cannot proceed, need help |
+
+### Benefits
+
+- Prevents revisiting same ground
+- Enables handoff to others
+- Creates learning artifact
+- Catches circular investigation
+- Documents what was tried
+
+## Root Cause Report
+
+Post-investigation documentation.
+
+### Template
+
+```markdown
+# Root Cause Analysis: {Issue Title}
+
+## Summary
+Brief description of issue and resolution in 2-3 sentences.
+
+## Timeline
+- {DATE/TIME}: Issue first observed
+- {DATE/TIME}: Investigation started
+- {DATE/TIME}: Root cause identified
+- {DATE/TIME}: Fix deployed
+- {DATE/TIME}: Issue verified resolved
+
+## Symptoms
+What users/systems experienced:
+- {Observable symptom 1}
+- {Observable symptom 2}
+
+## Root Cause
+**Primary cause**: {What ultimately caused the issue}
+
+**Contributing factors**:
+- {Factor that made issue worse or harder to catch}
+- {Factor that enabled issue to occur}
+
+## Evidence
+How we confirmed this was the root cause:
+- {Evidence 1}
+- {Evidence 2}
+- {Test that confirmed}
+
+## Resolution
+**Immediate fix**: {What was done to resolve}
+
+**Code/config changes**: {Links to PRs, commits}
+
+## Prevention
+**How to prevent recurrence**:
+- {Preventive measure 1}
+- {Preventive measure 2}
+
+**Detection improvements**:
+- {How to catch this earlier next time}
+
+## Lessons Learned
+- {What went well in investigation}
+- {What could improve}
+- {Knowledge gap discovered}
+
+## Appendix
+- Investigation log
+- Relevant logs/screenshots
+- Related incidents
+```
+
+## Quick Incident Notes
+
+For minor issues not requiring full RCA.
+
+### Template
+
+```markdown
+## Incident: {Brief title}
+**Date**: {When}
+**Duration**: {How long}
+**Impact**: {Who/what affected}
+
+**Cause**: {One sentence}
+**Fix**: {One sentence}
+**Prevention**: {One sentence}
+```
+
+## Hypothesis Tracking
+
+When testing multiple hypotheses.
+
+### Template
+
+```markdown
+## Hypotheses
+
+### H1: {Description}
+- **Likelihood**: High/Medium/Low
+- **Evidence for**: {Supporting data}
+- **Evidence against**: {Contradicting data}
+- **Test**: {How to verify}
+- **Status**: Pending/Testing/Confirmed/Ruled Out
+
+### H2: {Description}
+...
+```
+
+### Status Flow
+
+```
+Pending → Testing → Confirmed
+                 → Ruled Out
+```
+
+## Environment Snapshot
+
+Document system state at time of issue.
+
+### Template
+
+```markdown
+## Environment Snapshot
+
+**System**: {Service/application name}
+**Instance**: {Server/container ID}
+**Time**: {Timestamp}
+
+### Versions
+- Application: {version}
+- Runtime: {version}
+- Key dependencies: {versions}
+
+### Configuration
+- {Relevant config values}
+
+### State
+- Memory: {usage}
+- CPU: {usage}
+- Connections: {counts}
+- Queue depth: {if applicable}
+
+### Recent Changes
+- {Deploy/config change within last 24-48h}
+```
+
+## Postmortem Meeting Notes
+
+For team discussions.
+
+### Agenda Template
+
+```markdown
+## Postmortem: {Incident}
+**Date**: {Meeting date}
+**Attendees**: {Names}
+
+### Summary (5 min)
+{Owner presents incident summary}
+
+### Timeline Review (10 min)
+{Walk through what happened when}
+
+### Root Cause Discussion (15 min)
+- Confirmed root cause
+- Contributing factors
+- Why wasn't this caught earlier?
+
+### Action Items (15 min)
+| Action | Owner | Due Date |
+|--------|-------|----------|
+| {Preventive measure} | {Name} | {Date} |
+
+### Follow-up
+- Next review: {Date if needed}
+- Documentation: {Where RCA will be stored}
+```
+
+## Checklist: Documentation Quality
+
+Before closing investigation:
+
+- [ ] Root cause clearly stated
+- [ ] Evidence documented
+- [ ] Alternative hypotheses addressed
+- [ ] Resolution steps recorded
+- [ ] Prevention measures identified
+- [ ] Learning captured
+- [ ] Stakeholders informed
@@ -0,0 +1,233 @@
+# Elimination Techniques
+
+Systematic methods for narrowing problem scope.
+
+## Binary Search
+
+Halving the problem space with each test.
+
+### When to Use
+
+- Large problem space
+- Changes have clear ordering (time, code versions, config options)
+- Tests are quick relative to problem size
+
+### Process
+
+```
+1. Identify range: known-good state → known-bad state
+2. Test midpoint: does issue exist here?
+3. Narrow range: move to half containing issue
+4. Repeat: until single change identified
+```
+
+### Example: Git Bisect
+
+```bash
+# Automated binary search through commits
+git bisect start
+git bisect bad HEAD           # Current commit is bad
+git bisect good v1.2.0        # Known good version
+git bisect run ./test.sh      # Automatically find breaking commit
+```
+
+### Example: Configuration
+
+```
+50 config options, one causes issue
+
+Round 1: Test with first 25 options only
+  → Issue present → problem in first 25
+Round 2: Test with first 12 options only
+  → Issue absent → problem in options 13-25
+Round 3: Test with options 13-18
+  → Issue present → problem in 13-18
+...continue until single option found
+```
+
+### Efficiency
+
+| Problem Size | Binary Search Steps | Linear Search Steps |
+|--------------|---------------------|---------------------|
+| 10 items | ~4 | 10 |
+| 100 items | ~7 | 100 |
+| 1000 items | ~10 | 1000 |
+
+## Variable Isolation
+
+Changing one thing at a time.
+
+### When to Use
+
+- Multiple variables could be cause
+- Interactions between variables possible
+- Need to establish clear causation
+
+### Process
+
+```
+1. Baseline: measure with all defaults
+2. Change X only: measure impact
+3. Revert X, change Y only: measure impact
+4. Repeat for each variable
+5. If interactions suspected: test combinations
+```
+
+### Example: Performance Degradation
+
+```
+Suspects: new library version, config change, increased data volume
+
+Test 1: Revert library only → no change → not library
+Test 2: Revert config only → improvement → config contributes
+Test 3: Reduce data volume → improvement → data also contributes
+Test 4: Both config + data → full improvement → both factors
+
+Root cause: Config change + data growth interaction
+```
+
+### Common Mistakes
+
+- Changing multiple variables at once
+- Not reverting between tests
+- Assuming first positive result is complete answer
+- Not testing combinations when interactions possible
+
+## Process of Elimination
+
+Systematically ruling out possibilities.
+
+### When to Use
+
+- Finite set of possible causes
+- Can definitively rule things out
+- Structured environment
+
+### Process
+
+```
+Start with: All possible causes
+For each possibility:
+  - Design test to rule out
+  - Execute test
+  - If ruled out: remove from list
+  - If not ruled out: keep on list
+Continue until: single possibility remains
+```
+
+### Documentation Format
+
+```
+Possible causes:
+✗ Component A — ruled out: reproduced without A present
+✗ Component B — ruled out: tested in isolation, worked
+✗ External factor — ruled out: reproduced in clean environment
+○ Component C — not yet tested
+✓ Component D — confirmed: removing D fixes issue
+```
+
+### Example: Integration Failure
+
+```
+System: API → Queue → Worker → Database
+
+Test 1: Call API directly, bypass queue
+  → Issue persists → not queue-related
+
+Test 2: Worker processes test message
+  → Success → worker + database OK
+
+Test 3: Examine API-to-queue handoff
+  → Found: message format incorrect
+
+Root cause: API serialization bug
+```
+
+## Divide and Conquer
+
+Breaking complex system into testable segments.
+
+### When to Use
+
+- Complex multi-component systems
+- Don't know which area to focus on
+- Want to parallelize investigation
+
+### Process
+
+```
+1. Map system components
+2. Identify boundaries between components
+3. Test at each boundary: is data correct here?
+4. Find boundary where data becomes incorrect
+5. Focus investigation on that component
+```
+
+### Example: Data Pipeline
+
+```
+Source → Ingestion → Transform → Validation → Storage → API
+
+Check at each stage:
+- After Ingestion: data correct ✓
+- After Transform: data correct ✓
+- After Validation: data INCORRECT ✗
+
+Root cause is in Validation stage.
+```
+
+## Environment Bisection
+
+Isolating environment-specific factors.
+
+### When to Use
+
+- "Works on my machine" situations
+- Environment-dependent bugs
+- Deployment issues
+
+### Process
+
+```
+1. List environment differences (OS, versions, config, resources)
+2. Create minimal diff between working and failing
+3. Test with progressive alignment
+4. Identify minimum difference causing failure
+```
+
+### Difference Checklist
+
+| Category | Working | Failing |
+|----------|---------|---------|
+| OS/Version | | |
+| Runtime version | | |
+| Dependencies | | |
+| Config files | | |
+| Environment variables | | |
+| Network/ports | | |
+| Permissions | | |
+| Resource limits | | |
+
+## Technique Selection Guide
+
+| Situation | Recommended Technique |
+|-----------|----------------------|
+| Many commits to check | Binary search (git bisect) |
+| Multiple config options | Variable isolation |
+| Finite component list | Process of elimination |
+| Multi-stage pipeline | Divide and conquer |
+| "Works elsewhere" | Environment bisection |
+| Unknown scope | Start with divide and conquer, then specialize |
+
+## Combining Techniques
+
+Often multiple techniques used together:
+
+```
+1. Divide and conquer: narrow to subsystem
+2. Process of elimination: rule out components in subsystem
+3. Variable isolation: identify specific configuration
+4. Binary search: find when it broke
+```
+
+Each technique narrows scope; combine for efficiency.
@@ -0,0 +1,173 @@
+# Common Pitfalls
+
+Cognitive biases and resistance patterns that derail root cause investigation.
+
+## Resistance Patterns
+
+Rationalizations that prevent finding root cause:
+
+| Thought | Why It's Wrong | Counter |
+|---------|----------------|---------|
+| "I already looked at that" | Memory is unreliable under pressure | Re-examine with fresh evidence |
+| "That can't be the issue" | Assumptions block investigation | Test anyway, let evidence decide |
+| "We need to fix this quickly" | Pressure leads to random changes | Methodical investigation is faster |
+| "The logs don't show anything" | Absence of evidence != evidence of absence | Consider what logs might be missing |
+| "It worked before" | Systems change constantly | Past behavior doesn't guarantee current |
+| "Let me just try this one thing" | Random trial without hypothesis wastes time | Form hypothesis first |
+
+### Warning Signs
+
+You're falling into resistance when:
+- Same thoughts recurring without new evidence
+- Feeling defensive about previous conclusions
+- Avoiding re-testing areas you "already checked"
+- Making changes without understanding why they might work
+
+### Recovery
+
+When you catch yourself:
+1. Pause the investigation
+2. Write down current assumptions
+3. Challenge each assumption with "how do I know this?"
+4. Return to methodology
+
+## Confirmation Bias
+
+Tendency to see evidence supporting existing beliefs.
+
+### Manifestations
+
+- Seeing only evidence supporting pet hypothesis
+- Dismissing contradictory data as "noise"
+- Stopping investigation once "a" cause is found
+- Interpreting ambiguous evidence favorably
+
+### Counter-Strategies
+
+**Actively seek disconfirmation**:
+- Ask "what would prove me wrong?"
+- Design tests specifically to disprove hypothesis
+- Have someone else review your reasoning
+
+**Test alternative hypotheses**:
+- Even when confident in one theory
+- Especially when confident in one theory
+- Give each hypothesis fair testing time
+
+**Document objectively**:
+- Record all evidence, not just supporting evidence
+- Note your confidence level before and after tests
+- Track hypothesis changes over time
+
+## Correlation vs Causation
+
+Mistaking timing for cause.
+
+### Common Mistakes
+
+| Observation | Faulty Conclusion |
+|-------------|-------------------|
+| "It started when X changed" | X caused it |
+| "Happens at specific time" | Time is the cause |
+| "Only affects user Y" | User Y is doing something wrong |
+| "Works after restart" | Memory/state is the issue |
+
+### Verification Steps
+
+1. **Test direct causal mechanism** — Can you explain HOW X causes the symptom?
+2. **Look for confounding variables** — What else changed or varies?
+3. **Verify by removing supposed cause** — Does removing X fix it?
+4. **Test in isolation** — Does X cause it when nothing else varies?
+
+### Example
+
+Observation: "Bug only appears on Mondays"
+
+Bad conclusion: "Something about Monday causes the bug"
+
+Better investigation:
+- What's different on Monday? (traffic patterns, batch jobs, fresh caches)
+- Is it Monday specifically or "first day after weekend"?
+- Does it happen on holidays?
+- What runs over the weekend?
+
+## Anchoring
+
+Over-reliance on first piece of information.
+
+### Manifestations
+
+- First hypothesis dominates thinking
+- Initial symptom description defines investigation
+- Early evidence weighted more heavily
+- Difficulty abandoning initial direction
+
+### Counter-Strategies
+
+- Explicitly generate 3+ hypotheses before testing any
+- Weight evidence by quality, not order discovered
+- Periodically re-read original problem statement
+- Ask "what if my first assumption is wrong?"
+
+## Availability Heuristic
+
+Over-weighting recent or memorable experiences.
+
+### Manifestations
+
+- "This looks like the bug we had last week"
+- Assuming familiar problems over unfamiliar ones
+- Checking usual suspects first (sometimes good, often biasing)
+
+### Counter-Strategies
+
+- Consider base rates (how often does this actually happen?)
+- Check if "familiar" actually matches evidence
+- Maintain systematic approach even when "obvious"
+
+## Premature Closure
+
+Stopping investigation too early.
+
+### Warning Signs
+
+- Relief when finding "a" cause
+- Desire to move to fix stage quickly
+- Skipping verification steps
+- Not testing alternative hypotheses
+
+### Prevention
+
+- Multiple working hypotheses rule
+- Require explicit disconfirmation of alternatives
+- Verification stage mandatory before declaring root cause
+- Ask "what else could cause this symptom?"
+
+## Sunk Cost Fallacy
+
+Continuing failed approach due to invested effort.
+
+### Manifestations
+
+- "We've spent hours on this theory, it must be right"
+- Reluctance to abandon promising-but-wrong direction
+- Adding complexity to failing hypothesis instead of reconsidering
+
+### Counter-Strategies
+
+- Time-box hypothesis testing
+- Set explicit abandon criteria before starting
+- Treat investigation time as learning, not investment
+- Ask "if I started fresh, would I pursue this?"
+
+## Escalation Protocol
+
+When you recognize you're stuck in a pitfall:
+
+1. **Acknowledge** — Name the bias or pattern
+2. **Document** — Write down current state and reasoning
+3. **Reset** — Return to discovery stage
+4. **Reframe** — Look at problem from different angle
+5. **Seek outside perspective** — Fresh eyes often see what you miss
+
+If stuck for > 2x expected time, mandatory escalation or perspective shift.