@minko-ai/minko 0.1.0 → 0.1.1

package/assets/skills/five-whys/references/software-patterns.md

@@ -0,0 +1,284 @@
+# Common Root Cause Patterns in Software
+
+Frequently encountered root causes when applying 5-Whys to software problems.
+
+---
+
+## Pattern 1: Missing Error Handling
+
+### Typical Chain
+```
+Problem: Service returns 500 error intermittently
+Why 1: Unhandled exception in payment processing
+Why 2: External API returned unexpected format
+Why 3: API version changed without notice
+Why 4: No schema validation on API response
+Why 5: Error handling assumes happy path only
+```
+
+### Root Cause Type
+**Design Gap** - Defensive programming not applied
+
+### Countermeasures
+| Type | Action |
+|------|--------|
+| Immediate | Add try-catch, return graceful error |
+| Preventive | Schema validation on all external inputs |
+| Detection | Alert on unexpected response formats |
+
+---
+
+## Pattern 2: Resource Leaks
+
+### Typical Chain
+```
+Problem: Application memory grows until OOM
+Why 1: Heap usage increases over time
+Why 2: Objects not garbage collected
+Why 3: References held in static cache
+Why 4: Cache has no eviction policy
+Why 5: Cache designed for small dataset, now large
+```
+
+### Root Cause Type
+**Scaling Assumption** - Design didn't account for growth
+
+### Countermeasures
+| Type | Action |
+|------|--------|
+| Immediate | Restart service, add memory |
+| Preventive | LRU cache with size limits |
+| Detection | Memory usage alerts at 80% |
+
+---
+
+## Pattern 3: Race Conditions
+
+### Typical Chain
+```
+Problem: Duplicate orders created occasionally
+Why 1: Same order inserted twice
+Why 2: Two requests processed simultaneously
+Why 3: No idempotency key check
+Why 4: Assumed single request per order
+Why 5: No distributed system thinking in design
+```
+
+### Root Cause Type
+**Concurrency Gap** - Single-threaded assumptions in distributed system
+
+### Countermeasures
+| Type | Action |
+|------|--------|
+| Immediate | Database unique constraint |
+| Preventive | Idempotency keys required |
+| Detection | Duplicate detection in monitoring |
+
+---
+
+## Pattern 4: Configuration Drift
+
+### Typical Chain
+```
+Problem: Feature works in staging, fails in prod
+Why 1: Environment variable missing in prod
+Why 2: Manual deployment missed the variable
+Why 3: No config validation at startup
+Why 4: No infrastructure-as-code for env vars
+Why 5: Config management treated as afterthought
+```
+
+### Root Cause Type
+**Process Gap** - Manual process where automation needed
+
+### Countermeasures
+| Type | Action |
+|------|--------|
+| Immediate | Add missing config |
+| Preventive | IaC for all configuration |
+| Detection | Config diff check in CI/CD |
+
+---
+
+## Pattern 5: Cascade Failures
+
+### Typical Chain
+```
+Problem: All services down during traffic spike
+Why 1: Database connection pool exhausted
+Why 2: Queries taking 10x longer than normal
+Why 3: Missing index on new query pattern
+Why 4: New feature added query without review
+Why 5: No query performance review in PR process
+```
+
+### Root Cause Type
+**Process Gap** - Missing review step
+
+### Countermeasures
+| Type | Action |
+|------|--------|
+| Immediate | Add index, restart services |
+| Preventive | Query review checklist in PR |
+| Detection | Query latency alerts |
+
+---
+
+## Pattern 6: Security Vulnerabilities
+
+### Typical Chain
+```
+Problem: SQL injection found in production
+Why 1: User input directly in SQL query
+Why 2: Using string concatenation for queries
+Why 3: Developer unaware of parameterized queries
+Why 4: No security training for new developers
+Why 5: Security not part of onboarding process
+```
+
+### Root Cause Type
+**Knowledge Gap** - Training/onboarding deficiency
+
+### Countermeasures
+| Type | Action |
+|------|--------|
+| Immediate | Fix query, audit similar code |
+| Preventive | Security training mandatory |
+| Detection | Static analysis in CI |
+
+---
+
+## Pattern 7: Dependency Failures
+
+### Typical Chain
+```
+Problem: Build failed after weekend
+Why 1: npm install fails
+Why 2: Package version no longer exists
+Why 3: Using floating version (^1.0.0)
+Why 4: Lock file not committed
+Why 5: No policy on dependency pinning
+```
+
+### Root Cause Type
+**Policy Gap** - Missing standard/guideline
+
+### Countermeasures
+| Type | Action |
+|------|--------|
+| Immediate | Pin version, commit lock file |
+| Preventive | Require lock files in all repos |
+| Detection | CI fails if lock file missing |
+
+---
+
+## Pattern 8: Data Corruption
+
+### Typical Chain
+```
+Problem: Users see wrong account balance
+Why 1: Balance calculation includes deleted transactions
+Why 2: Soft delete not filtered in query
+Why 3: New query copied from old one without filter
+Why 4: No standard query patterns/repository layer
+Why 5: Each feature writes raw SQL independently
+```
+
+### Root Cause Type
+**Architecture Gap** - Missing abstraction layer
+
+### Countermeasures
+| Type | Action |
+|------|--------|
+| Immediate | Fix query, audit similar |
+| Preventive | Repository pattern with standard filters |
+| Detection | Data consistency checks |
+
+---
+
+## Root Cause Categories Summary
+
+| Category | Description | Typical Fix |
+|----------|-------------|-------------|
+| **Design Gap** | Missing consideration in design | Redesign component |
+| **Process Gap** | Manual where automation needed | Automate process |
+| **Knowledge Gap** | Team missing skill/awareness | Training, documentation |
+| **Policy Gap** | No standard/guideline exists | Create and enforce policy |
+| **Architecture Gap** | Missing abstraction/pattern | Refactor architecture |
+| **Scaling Assumption** | Design didn't anticipate growth | Redesign for scale |
+| **Concurrency Gap** | Single-thread thinking in distributed | Add synchronization |
+
+---
+
+## Anti-Patterns in 5-Whys
+
+### Anti-Pattern 1: The Blame Game
+```
+❌ Wrong:
+Why 5: Developer didn't test properly
+
+✓ Right:
+Why 5: No automated test coverage for this scenario
+```
+
+### Anti-Pattern 2: The Vendor Excuse
+```
+❌ Wrong:
+Why 5: Third-party API is unreliable
+
+✓ Right:
+Why 5: No retry/fallback for external dependencies
+```
+
+### Anti-Pattern 3: The Resource Excuse
+```
+❌ Wrong:
+Why 5: We don't have time to do it right
+
+✓ Right:
+Why 5: Technical debt not prioritized in planning
+```
+
+### Anti-Pattern 4: The Complexity Excuse
+```
+❌ Wrong:
+Why 5: The system is too complex
+
+✓ Right:
+Why 5: No documentation/tests for complex interactions
+```
+
+---
+
+## Template for Software Issues
+
+```markdown
+## 5-Whys: [Issue Title]
+
+### Problem
+- **Symptom:** [What users/monitoring saw]
+- **Time:** [When detected]
+- **Duration:** [How long]
+- **Impact:** [Users/revenue affected]
+
+### Analysis
+
+| Why | Question | Answer | Evidence |
+|-----|----------|--------|----------|
+| 1 | Why did [symptom]? | | Logs/metrics |
+| 2 | Why did [Why1]? | | Code/config |
+| 3 | Why did [Why2]? | | History/commits |
+| 4 | Why did [Why3]? | | Process/docs |
+| 5 | Why did [Why4]? | | Policy/culture |
+
+### Root Cause
+- **Category:** [Design/Process/Knowledge/Policy/Architecture]
+- **Statement:** [One sentence]
+
+### Actions
+| Priority | Action | Owner | Status |
+|----------|--------|-------|--------|
+| P0 | [Immediate fix] | | |
+| P1 | [Prevention] | | |
+| P2 | [Detection] | | |
+```

package/assets/skills/five-whys/references/toyota-origins.md

@@ -0,0 +1,257 @@
+# 5-Whys: Toyota Origins and Principles
+
+The history and core principles of 5-Whys from the Toyota Production System.
+
+---
+
+## Historical Background
+
+### Origin
+The 5-Whys technique was developed by **Sakichi Toyoda** (founder of Toyota Industries) and later refined by **Taiichi Ohno** as a critical component of the Toyota Production System (TPS) in the 1950s.
+
+### The Famous Example
+
+Taiichi Ohno's classic example from the factory floor:
+
+```
+Problem: The robot stopped working
+
+Why 1: Why did the robot stop?
+→ The circuit has overloaded, causing a fuse to blow.
+
+Why 2: Why is the circuit overloaded?
+→ There was insufficient lubrication on the bearings, so they locked up.
+
+Why 3: Why was there insufficient lubrication?
+→ The oil pump on the robot is not circulating sufficient oil.
+
+Why 4: Why is the pump not circulating sufficient oil?
+→ The pump intake is clogged with metal shavings.
+
+Why 5: Why is the intake clogged with metal shavings?
+→ There is no filter on the pump.
+
+Root Cause: No filter on the oil pump intake
+Solution: Install a filter on the oil pump
+```
+
+**Key Insight:** Without 5-Whys, the "fix" would have been replacing the fuse—and the robot would fail again.
+
+---
+
+## Core Principles from Toyota
+
+### Principle 1: Go and See (Genchi Genbutsu)
+
+**Definition:** Go to the actual place, see the actual situation, understand the actual facts.
+
+**Application to 5-Whys:**
+- Don't analyze from reports alone
+- Verify each "why" with direct observation
+- Evidence must be firsthand, not hearsay
+
+**Software Equivalent:**
+- Read the actual logs, not summaries
+- Check the actual code, not just the description
+- Verify in the actual environment where the problem occurred
+
+### Principle 2: Respect for People
+
+**Definition:** Problems are process problems, not people problems.
+
+**Application to 5-Whys:**
+- Never stop at "human error" as root cause
+- Ask "why did the process allow this error?"
+- Build systems that make errors impossible or obvious
+
+**The Toyota Philosophy:**
+> "Blame the process, not the person. Every defect is a gift—it reveals a weakness in our process that we can improve."
+
+### Principle 3: Continuous Improvement (Kaizen)
+
+**Definition:** Small, incremental improvements every day.
+
+**Application to 5-Whys:**
+- Each root cause found is an improvement opportunity
+- Document learnings for future reference
+- Share findings across teams
+
+### Principle 4: Build Quality In (Jidoka)
+
+**Definition:** Stop and fix problems when they occur, don't pass them on.
+
+**Application to 5-Whys:**
+- Address root causes immediately
+- Prevention > detection > reaction
+- Make problems visible
+
+---
+
+## The "5" in 5-Whys
+
+### Why Specifically Five?
+
+**Short Answer:** Five is a guideline, not a rule.
+
+**Ohno's Observation:**
+> "By asking 'why' five times, the nature of the problem as well as its solution becomes clear."
+
+**The Reality:**
+- Some problems need only 3 whys
+- Some need 7 or more
+- Stop when you reach an actionable root cause
+
+### Signs You've Gone Deep Enough
+
+| Signal | Example |
+|--------|---------|
+| Reached a process/policy | "No code review requirement" |
+| Found a missing control | "No input validation" |
+| Hit a design decision | "Chose eventual consistency" |
+| Discovered a trade-off | "Prioritized speed over testing" |
+
+### Signs You Need to Go Deeper
+
+| Signal | Example |
+|--------|---------|
+| Answer is still a symptom | "The server was slow" |
+| Answer is blame | "Developer made a mistake" |
+| Answer is vague | "Something went wrong" |
+| Problem will recur if unchanged | "Bad data was entered" |
+
+---
+
+## Toyota vs. Software Context
+
+### Similarities
+
+| Toyota Factory | Software System |
+|----------------|-----------------|
+| Assembly line stops | Production incident |
+| Defective part | Bug in code |
+| Machine breakdown | Service outage |
+| Quality inspection | Testing/monitoring |
+| Process variation | Configuration drift |
+
+### Key Differences
+
+| Aspect | Toyota Factory | Software |
+|--------|----------------|----------|
+| **Visibility** | Physical, observable | Abstract, logged |
+| **Reproducibility** | High | Variable (race conditions) |
+| **Root cause location** | Usually nearby | Could be anywhere in stack |
+| **Fix deployment** | Immediate | Requires release process |
+| **Evidence** | Physical inspection | Logs, metrics, traces |
+
+### Adaptations for Software
+
+1. **Distributed Systems Complexity**
+   - Multiple services may contribute to one problem
+   - Need to trace across service boundaries
+   - Consider timing and ordering of events
+
+2. **Non-Determinism**
+   - Some bugs don't reproduce reliably
+   - May need statistical evidence
+   - "Why does this happen 5% of the time?"
+
+3. **Remote Evidence Gathering**
+   - Can't physically "go and see"
+   - Rely on observability (logs, metrics, traces)
+   - Need good instrumentation
+
+---
+
+## Toyota's 5-Whys Best Practices
+
+### Practice 1: Write It Down
+
+Toyota engineers document every 5-Whys analysis. Benefits:
+- Forces clear thinking
+- Creates reference for future problems
+- Enables pattern recognition across incidents
+
+### Practice 2: Do It Together
+
+At Toyota, 5-Whys is a team activity:
+- Multiple perspectives catch blind spots
+- Shared understanding of the problem
+- Collective ownership of the solution
+
+### Practice 3: Verify Before Moving On
+
+Each "why" must be verified before proceeding:
+- "How do we know this is true?"
+- "What evidence supports this?"
+- "Have we seen this directly?"
+
+### Practice 4: Focus on Process
+
+Toyota's hierarchy of root causes:
+1. **Best:** Fix the process/system
+2. **Good:** Add a check/validation
+3. **Acceptable:** Add training/documentation
+4. **Avoid:** Rely on human vigilance
+
+### Practice 5: Follow Through
+
+Analysis without action is waste:
+- Assign owners to countermeasures
+- Set deadlines
+- Verify effectiveness
+
+---
+
+## Common Mistakes Toyota Warns Against
+
+### Mistake 1: Jumping to Solutions
+
+> "The most dangerous kind of waste is the waste we do not recognize." — Shigeo Shingo
+
+Wait until 5-Whys is complete before proposing solutions.
+
+### Mistake 2: Stopping at Symptoms
+
+If your root cause could be preceded by "because," you haven't gone deep enough.
+
+### Mistake 3: Single-Cause Thinking
+
+Real problems often have multiple contributing factors. Use branching when needed.
+
+### Mistake 4: Accepting "Human Error"
+
+> "Every human error is a process error in disguise." — Toyota principle
+
+Always ask: "Why did the process allow this error?"
+
+---
+
+## The Toyota Way Summary
+
+| Principle | 5-Whys Application |
+|-----------|-------------------|
+| **Challenge** | Question every assumption |
+| **Kaizen** | Every problem is an improvement opportunity |
+| **Genchi Genbutsu** | Base analysis on facts, not opinions |
+| **Respect** | Fix processes, don't blame people |
+| **Teamwork** | Analyze together, own together |
+
+---
+
+## Applying Toyota Wisdom to Software
+
+**Before starting 5-Whys:**
+- Gather all available evidence (logs, metrics, traces)
+- Involve people who were there when it happened
+- Create a timeline of events
+
+**During 5-Whys:**
+- Verify each level with evidence
+- Branch when multiple causes contribute
+- Keep asking until you reach process/design
+
+**After 5-Whys:**
+- Document the analysis
+- Assign owners to countermeasures
+- Share learnings with the team
+- Verify fixes are effective

package/assets/skills/systematic-debugging/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.