omgkit 2.1.1 → 2.3.0

package/plugin/skills/methodology/root-cause-tracing/SKILL.md

@@ -1,53 +1,88 @@
 ---
-name: root-cause-tracing
-description: Finding root causes. Use when debugging complex issues.
+name: tracing-root-causes
+description: AI agent performs systematic root cause analysis using 5 Whys, Fishbone diagrams, and evidence-based investigation. Use when debugging, conducting post-mortems, or investigating incidents.
 ---
 
-# Root Cause Tracing Skill
+# Tracing Root Causes
 
-## 5 Whys
-```
-Problem: App crashed
-Why? → Out of memory
-Why? → Memory leak
-Why? → Event listeners not cleaned
-Why? → Missing cleanup in useEffect
-Why? → Developer unaware of cleanup pattern
-Root: Training/documentation gap
-```
+## Quick Start
 
-## Fishbone Diagram
-```
-                    ┌─ Code
-                    ├─ Config
-Problem ────────────├─ Environment
-                    ├─ Data
-                    └─ Dependencies
-```
+1. **Identify Symptom** - Document the observable problem
+2. **Gather Evidence** - Collect logs, metrics, traces around incident
+3. **Apply 5 Whys** - Ask "Why?" iteratively until fundamental cause found
+4. **Map Categories** - Use Fishbone to explore all cause categories
+5. **Document Findings** - Create RCA report with action items
 
-## Categories
-1. **Code** - Bug in logic
-2. **Data** - Invalid input
-3. **Config** - Wrong settings
-4. **Environment** - System issues
-5. **External** - Third-party failure
+## Features
 
-## Output
-```markdown
-## Root Cause Analysis
+| Feature | Description | Guide |
+|---------|-------------|-------|
+| Cause Hierarchy | Symptom -> Proximate -> Root -> Systemic | Fix at deepest level possible |
+| 5 Whys | Iterative "Why?" questioning | Typically 5 iterations to root cause |
+| Fishbone Diagram | Category-based cause exploration | Code, Data, Config, Infra, External, Process |
+| Evidence Gathering | Logs, metrics, traces, reproduction | Timestamp, source, reliability rating |
+| RCA Report | Structured documentation | Timeline, cause chain, action items |
+| Systemic Factors | Why wasn't this caught earlier? | Testing, monitoring, process gaps |
 
-### Symptom
-[What was observed]
+## Common Patterns
 
-### Proximate Cause
-[Immediate cause]
+```
+# 5 Whys Example
+Problem: Website down for 2 hours
+
+Why #1: Why down? -> Server out of memory
+Why #2: Why out of memory? -> Connections unbounded
+Why #3: Why unbounded? -> Not released after use
+Why #4: Why not released? -> Early return skipped finally
+Why #5: Why not caught? -> No test for cleanup path
 
-### Root Cause
-[Underlying reason]
+Root Causes:
+1. Technical: Missing cleanup execution
+2. Systemic: Missing test coverage
+3. Process: Code review missed pattern
 
-### Systemic Factors
-[Why it wasn't caught]
+# Fishbone Categories (Software)
+CODE:       Logic errors, race conditions, memory leaks
+DATA:       Invalid input, corrupt data, schema mismatch
+CONFIG:     Wrong settings, env mismatch, feature flags
+INFRA:      Resource exhaustion, network, scaling
+EXTERNAL:   Third-party APIs, dependencies, attacks
+PROCESS:    Missing tests, review gaps, monitoring blind spots
+```
 
-### Prevention
-[How to prevent recurrence]
 ```
+# Cause Hierarchy
+SYMPTOM: "App crashed"
+    |
+PROXIMATE CAUSE: "Out of memory"
+    |
+CONTRIBUTING FACTOR: "No memory limits"
+    |
+ROOT CAUSE: "Memory leak in event handlers"
+    |
+SYSTEMIC FACTOR: "No memory monitoring"
+
+PRINCIPLE: Fix symptoms = problem returns
+           Fix root cause = this problem prevented
+           Fix systemic = class of problems prevented
+```
+
+## Best Practices
+
+| Do | Avoid |
+|----|-------|
+| Gather evidence before forming hypotheses | Jumping to conclusions |
+| Use structured methods consistently | Ad-hoc investigation |
+| Involve multiple perspectives | Single viewpoint |
+| Look for systemic factors | Just fixing immediate cause |
+| Create actionable recommendations | Vague "be more careful" |
+| Verify fixes prevent recurrence | Assuming fix works |
+| Share learnings across team | Siloing knowledge |
+| Investigate near-misses too | Only investigating failures |
+
+## Related Skills
+
+- `debugging-systematically` - Four-phase debugging process
+- `solving-problems` - 5-phase problem-solving framework
+- `thinking-sequentially` - Numbered thought chains
+- `verifying-before-completion` - Ensure fix completeness

package/plugin/skills/methodology/sequential-thinking/SKILL.md

@@ -1,260 +1,111 @@
 ---
-name: sequential-thinking
-description: Numbered thought sequences for complex problem decomposition and structured reasoning
+name: thinking-sequentially
+description: AI agent structures complex reasoning through numbered thought sequences with explicit dependencies. Use when facing multi-step problems, complex debugging, or architectural decisions.
 category: methodology
 triggers:
-  - complex problem
+  - sequential thinking
   - step by step
-  - think through
   - reasoning chain
-  - decompose
+  - thought process
+  - complex problem
 ---
 
-# Sequential Thinking
-
-Master the art of **structured reasoning** through numbered thought sequences. This skill enables systematic problem decomposition, dependency tracking, and clear reasoning chains for complex challenges.
+# Thinking Sequentially
 
 ## Purpose
 
-Sequential thinking transforms chaotic problem-solving into organized, traceable reasoning. It's essential when:
-
-- Problems have multiple interdependent components
-- Solutions require building on previous insights
-- Team communication needs clear reasoning trails
-- Debugging requires systematic elimination
-- Decisions need documented justification
-
-## Features
-
-### 1. Numbered Thought Chains
-```
-THOUGHT 1: Identify the core problem
-  - What exactly is failing?
-  - What is the expected behavior?
-
-THOUGHT 2: Establish constraints (depends on THOUGHT 1)
-  - What cannot change?
-  - What resources are available?
-
-THOUGHT 3: Generate hypotheses (depends on THOUGHT 1, 2)
-  - Hypothesis A: Configuration issue
-  - Hypothesis B: Data corruption
-  - Hypothesis C: Race condition
-```
-
-### 2. Dependency Tracking
-```
-[THOUGHT 4] ← depends on [THOUGHT 2, 3]
-This ensures we don't proceed without establishing prerequisites.
-Mark dependencies explicitly to enable:
-  - Parallel thinking on independent thoughts
-  - Clear revision paths when assumptions change
-  - Better collaboration handoffs
-```
-
-### 3. Revision and Backtracking
-```
-REVISION: Updating THOUGHT 3 based on new evidence
-  - Original: Assumed single-threaded execution
-  - New insight: System uses worker threads
-  - Impact: Hypothesis C (race condition) now most likely
-
-BACKTRACK: Returning to THOUGHT 2
-  - Constraint we missed: 100ms timeout requirement
-  - This invalidates THOUGHT 5-7, need to restart from here
-```
-
-### 4. Checkpoint Summaries
-```
-=== CHECKPOINT after THOUGHT 10 ===
-KEY FINDINGS:
-1. Root cause identified: Memory leak in cache layer
-2. Two viable solutions identified
-3. Solution A preferred (lower risk)
-
-OPEN QUESTIONS:
-- Performance impact of Solution A?
-- Rollback strategy needed?
-
-NEXT STEPS:
-- THOUGHT 11: Benchmark Solution A
-- THOUGHT 12: Design rollback procedure
-===================================
-```
-
-### 5. Visual Thought Mapping
-```
-                    [THOUGHT 1: Problem Definition]
-                           |
-              +------------+------------+
-              |                         |
-    [THOUGHT 2: Constraints]  [THOUGHT 3: Context]
-              |                         |
-              +------------+------------+
-                           |
-                [THOUGHT 4: Hypotheses]
-                     /    |    \
-                   /      |      \
-            [T5: H1]  [T6: H2]  [T7: H3]
-                         |
-                   [THOUGHT 8: Solution]
-```
-
-## Use Cases
-
-### Complex Algorithm Design
-```
-THOUGHT 1: Define the problem space
-  - Input: Unsorted array of N integers
-  - Output: K largest elements
-  - Constraint: O(N log K) time complexity
-
-THOUGHT 2: Evaluate known approaches
-  - Full sort: O(N log N) - too slow
-  - Min-heap of size K: O(N log K) - meets requirement
-  - QuickSelect: O(N) average - better but unstable
+Structure complex reasoning through numbered thought sequences:
 
-THOUGHT 3: Select approach (depends on THOUGHT 2)
-  - Choose min-heap for guaranteed performance
-  - QuickSelect as optimization for large N
+- Decompose multi-step problems into traceable chains
+- Track dependencies between insights explicitly
+- Create checkpoints for periodic review
+- Enable revision when assumptions change
+- Support parallel hypothesis exploration
 
-THOUGHT 4: Design implementation (depends on THOUGHT 3)
-  - Initialize min-heap with first K elements
-  - For remaining elements, compare with heap root
-  - If larger, replace root and heapify
-```
-
-### System Architecture Decisions
-```
-THOUGHT 1: Identify scaling bottleneck
-  - Database reads: 10,000 QPS
-  - Current capacity: 2,000 QPS
-  - Gap: 5x improvement needed
-
-THOUGHT 2: List scaling options
-  - Read replicas
-  - Caching layer
-  - Database sharding
-  - Query optimization
-
-THOUGHT 3: Evaluate trade-offs (depends on THOUGHT 1, 2)
-  | Option          | Complexity | Time | Cost  |
-  |-----------------|------------|------|-------|
-  | Read replicas   | Low        | 1w   | $500  |
-  | Caching         | Medium     | 2w   | $200  |
-  | Sharding        | High       | 4w   | $1000 |
-  | Query optimize  | Low        | 3d   | $0    |
-
-THOUGHT 4: Recommendation
-  - Immediate: Query optimization (quick win)
-  - Short-term: Caching layer
-  - Long-term: Read replicas as traffic grows
-```
-
-### Debugging Multi-Component Issues
-```
-THOUGHT 1: Reproduce the issue
-  - Steps: Login → Dashboard → Click "Export"
-  - Result: 500 error after 30 seconds
-  - Frequency: 100% reproducible
-
-THOUGHT 2: Identify affected components
-  - Frontend: React dashboard
-  - API: Node.js Express server
-  - Database: PostgreSQL
-  - External: S3 for file storage
-
-THOUGHT 3: Isolate the failure point (depends on THOUGHT 2)
-  - Frontend logs: Request sent successfully
-  - API logs: Request received, DB query started
-  - DB logs: Query completed in 2 seconds
-  - API logs: S3 upload started... [timeout]
-
-  FINDING: Issue is S3 upload timeout
+## Quick Start
 
-THOUGHT 4: Root cause analysis (depends on THOUGHT 3)
-  - S3 region: us-east-1
-  - Server region: eu-west-1
-  - File size: 50MB
-  - Network latency: 150ms
-
-  ROOT CAUSE: Cross-region upload with large file
-```
-
-## Best Practices
+1. **Define** - State the problem clearly as THOUGHT 1
+2. **Decompose** - Break into numbered thoughts with dependencies
+3. **Track** - Mark dependencies explicitly: "depends on THOUGHT 2"
+4. **Checkpoint** - Summarize every 5-10 thoughts
+5. **Revise** - Update thoughts when assumptions change, invalidate dependents
+6. **Branch** - Explore parallel hypotheses when needed
 
-### Do's
-- **Number every thought explicitly** - Enables reference and revision
-- **Mark dependencies clearly** - "This depends on THOUGHT 3"
-- **Allow revision** - "REVISION: Updating THOUGHT 2 based on..."
-- **Summarize at checkpoints** - Every 5-10 thoughts
-- **Time-box thoughts** - Prevent infinite exploration
+## Features
 
-### Don'ts
-- Don't skip numbering for "obvious" thoughts
-- Don't hide dependencies in prose
-- Don't delete invalid thoughts (strike through instead)
-- Don't exceed 20 thoughts without a checkpoint
-- Don't branch more than 3 levels deep
+| Feature | Description | Guide |
+|---------|-------------|-------|
+| Numbered Chains | Explicit THOUGHT 1, 2, 3... with IDs | Number every insight, never skip |
+| Dependencies | Mark what each thought relies on | `[THOUGHT 4] <- depends on [2, 3]` |
+| Checkpoints | Periodic summaries of findings | Every 5-10 thoughts, list key findings |
+| Revisions | Update previous thoughts with new data | Mark original as revised, create new |
+| Branching | Explore multiple hypotheses in parallel | Create named branches, select winner |
+| Visual Maps | Diagram thought relationships | ASCII diagrams for complex chains |
 
-### Templates
+## Common Patterns
 
-**Problem Analysis Template:**
 ```
+# Problem Analysis Pattern
 THOUGHT 1: Problem statement
 THOUGHT 2: Success criteria
 THOUGHT 3: Constraints
-THOUGHT 4: Assumptions (validate these!)
+THOUGHT 4: Assumptions (validate!)
 THOUGHT 5-N: Solution exploration
-CHECKPOINT: Summary and decision
-```
+=== CHECKPOINT ===
 
-**Decision Making Template:**
-```
+# Decision Making Pattern
 THOUGHT 1: Decision to make
 THOUGHT 2: Options identified
 THOUGHT 3-N: Evaluate each option
 THOUGHT N+1: Comparison matrix
-THOUGHT N+2: Recommendation with rationale
-```
-
-## Related Skills
+THOUGHT N+2: Recommendation
 
-- **writing-plans** - Use sequential thinking to create detailed plans
-- **brainstorming** - Generate options in THOUGHT steps
-- **problem-solving** - Apply systematic approaches
-- **root-cause-tracing** - Use numbered investigation steps
-- **systematic-debugging** - Structure debugging as thought chain
+# Investigation Pattern
+THOUGHT 1: What we observed
+THOUGHT 2: What we expected
+THOUGHT 3: Gap analysis
+THOUGHT 4-N: Hypothesis testing
+=== CHECKPOINT: Root cause ===
+```
 
-## Integration Example
+```
+# Visual thought mapping
+        [THOUGHT 1: Problem]
+               |
+    +----------+----------+
+    |                     |
+[THOUGHT 2]         [THOUGHT 3]
+    |                     |
+    +----------+----------+
+               |
+        [THOUGHT 4: Synthesis]
+```
 
-```markdown
-# Feature: User Authentication Redesign
+## Use Cases
 
-## Sequential Analysis
+- Multi-step debugging requiring traceable reasoning chains
+- Architectural decisions with complex trade-off analysis
+- Code review requiring systematic examination of multiple concerns
+- Root cause analysis with hypothesis tracking
+- Complex refactoring requiring dependency-aware planning
 
-THOUGHT 1: Current pain points
-- Session timeout too aggressive (15 min)
-- No "remember me" option
-- MFA required on every login
+## Best Practices
 
-THOUGHT 2: User research findings (external input)
-- 73% want "remember me"
-- 45% frustrated by frequent MFA
-- Security team requires MFA for sensitive actions
+| Do | Avoid |
+|----|-------|
+| Number every thought explicitly | Skipping numbers for "obvious" thoughts |
+| Mark dependencies clearly | Hiding dependencies in prose |
+| Summarize at checkpoints | Exceeding 20 thoughts without checkpoint |
+| Allow revision with reason | Deleting invalid thoughts (strike through) |
+| Time-box each thought | Infinite exploration without bounds |
+| Branch for parallel exploration | Branching more than 3 levels deep |
+| Validate assumptions early | Proceeding with invalidated dependencies |
 
-THOUGHT 3: Design constraints (depends on THOUGHT 1, 2)
-- Must maintain SOC2 compliance
-- Cannot increase session beyond 24h
-- MFA must protect financial transactions
+## Related Skills
 
-THOUGHT 4: Proposed solution (depends on THOUGHT 3)
-- Implement "remember device" (30 days)
-- Step-up MFA only for sensitive actions
-- Extend session to 60 min with activity
+See also these related skill documents for complementary techniques:
 
-=== CHECKPOINT ===
-Solution balances security and UX.
-Next: Security review before implementation.
-==================
-```
+- **writing-plans** - Structure plans as numbered thought sequences
+- **debugging-systematically** - Apply sequential debugging steps
+- **tracing-root-causes** - Use numbered investigation chains
+- **brainstorming-ideas** - Generate options in thought steps

package/plugin/skills/methodology/systematic-debugging/SKILL.md

@@ -1,50 +1,96 @@
 ---
-name: systematic-debugging
-description: Systematic debugging process. Use when investigating bugs.
+name: debugging-systematically
+description: AI agent follows a 5-phase debugging process with reproduction, isolation, hypothesis testing, and root cause resolution. Use when investigating bugs, troubleshooting issues, or hunting errors.
 ---
 
-# Systematic Debugging Skill
+# Debugging Systematically
 
-## Process
+## Quick Start
 
-### 1. Reproduce
-- Can you reproduce consistently?
-- What are the exact steps?
-- What environment?
+1. **Reproduce** - Create reliable reproduction steps, document environment
+2. **Isolate** - Binary search to narrow down, create minimal repro case
+3. **Hypothesize** - Generate 3+ theories with evidence and test cost
+4. **Test** - Design tests to prove/disprove each hypothesis
+5. **Fix & Verify** - Write failing test first, implement fix, verify green
 
-### 2. Isolate
-- What's the smallest case?
-- Which component fails?
-- When did it start?
+## Features
 
-### 3. Hypothesize
-Form 3 hypotheses:
-1. [Most likely cause]
-2. [Second possibility]
-3. [Unlikely but possible]
+| Feature | Description | Guide |
+|---------|-------------|-------|
+| Reproduction | Consistent steps to trigger bug | Exact steps, environment, frequency |
+| Isolation | Narrow down problem area | Binary search code, git bisect |
+| Hypothesis Ranking | Prioritize theories to test | Evidence strength x (1/test cost) |
+| Strategic Logging | Add targeted debug output | `[DEBUG][Service][method]` format |
+| Git Bisect | Find regression commit | `git bisect start`, mark good/bad |
+| Regression Tests | Prevent bug from returning | Write failing test before fixing |
 
-### 4. Test
-- Test each hypothesis
-- Use binary search for large codebases
-- Add logging strategically
+## Common Patterns
 
-### 5. Fix
-- Minimal fix first
-- Add regression test
-- Verify fix works
+```
+# Reproduction Template
+Environment:
+  OS: [version]
+  Node: [version]
+  Browser: [version]
+
+Steps:
+1. [Step 1]
+2. [Step 2]
+3. Observe: [Error]
+
+Frequency: 100% | Intermittent (~50%)
+First observed: [date]
+Last known good: [commit/version]
+
+# Isolation via Binary Search
+function problematic() {
+  // BLOCK A
+  await stepA1();
+  await stepA2();
+
+  // BLOCK B
+  await stepB1();
+  await stepB2();
+
+  // Comment out BLOCK B
+  // Still fails? Bug in BLOCK A
+  // Works now? Bug in BLOCK B
+}
 
-## Tools
-```bash
+# Git Bisect
 git bisect start
 git bisect bad HEAD
-git bisect good v1.0.0
+git bisect good v2.0.0
+# Git checks out middle, test and mark
+git bisect good  # or: git bisect bad
+# Repeat until culprit found
+git bisect reset
 ```
 
-## Output
-```markdown
-## Debug Report
-- Problem: [Description]
-- Root Cause: [Actual cause]
-- Fix: [What changed]
-- Prevention: [How to prevent]
 ```
+# Hypothesis Template
+| # | Hypothesis | Evidence | Test Cost | Priority |
+|---|------------|----------|-----------|----------|
+| H1 | Missing index | Seq scan in EXPLAIN | Low | 1st |
+| H2 | N+1 query | Loop in code | Low | 2nd |
+| H3 | Memory leak | Gradual increase | High | 3rd |
+```
+
+## Best Practices
+
+| Do | Avoid |
+|----|-------|
+| Always reproduce before debugging | Debugging without reproduction |
+| Write down hypotheses before testing | Testing multiple hypotheses at once |
+| Use binary search for large codebases | Random code changes |
+| Write failing test before fixing | Assuming cause without evidence |
+| Document the debugging session | Ignoring intermittent bugs |
+| Add logging strategically | Keeping debug code in production |
+| Check for related issues | Fixing symptoms instead of root cause |
+
+## Related Skills
+
+- `solving-problems` - 5-phase problem-solving framework
+- `tracing-root-causes` - 5 Whys and Fishbone analysis
+- `avoiding-testing-anti-patterns` - Prevent flaky tests
+- `verifying-before-completion` - Ensure fix is complete