@minko-ai/minko 0.1.0 → 0.1.1

package/assets/skills/cyclomatic-complexity/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: cyclomatic-complexity
+description: Refactor code to reduce cyclomatic complexity so it stays readable, maintainable, and aligned with the long-term vision of the codebase, not just optimized for AI comprehension. Use whenever the user asks to refactor, simplify, clean up, or review code quality; mentions complexity, maintainability, readability, spaghetti code, deeply nested logic, or god functions; or asks to check AI-generated code before merging. Also use proactively after writing any nontrivial function with heavy branching.
+---
+
+# Cyclomatic Complexity
+
+Purpose: AI-written code often works but branches like a jungle. This skill: measure complexity, refactor hotspots, keep code human-maintainable.
+
+## Measure first
+
+CC = decision points + 1. Decision points: `if`, `else if`, `case`, loops, `catch`, ternary, `&&`, `||` in conditions.
+
+Project linter config wins. If eslintrc, radon config, sonar config, or similar sets a complexity threshold, use that. No config: use defaults below.
+
+Thresholds:
+- 1-5: fine, leave alone
+- 6-10: watch, refactor if touching anyway
+- 11-15: refactor now
+- 15+: must split, no debate
+
+Prefer real tools over eyeballing when environment allows:
+- Python: `radon cc -s -a <path>`
+- JS/TS: eslint `complexity` rule
+- Go: `gocyclo`
+- Polyglot: `lizard <path>`
+
+No tool available: count manually, per function, show the count.
+
+## Refactor tactics, in order of preference
+
+1. **Guard clauses.** Invert conditions, return early, kill nesting.
+2. **Extract function.** Each extracted piece gets a name that says what, not how. Names are documentation.
+3. **Lookup table / map** instead of if-else or switch chains.
+4. **Named predicates.** `if (isEligibleForRefund(order))` beats a 4-clause boolean soup.
+5. **Polymorphism / strategy** for switch-on-type. Only when the switch appears in 2+ places.
+6. **Flatten loops.** Extract loop body, use continue instead of nested if.
+
+## Hard rules
+
+- Preserve behavior. Run tests before and after. No tests: say so, suggest adding, refactor conservatively.
+- Don't game the metric. A dense one-liner hiding 6 branches is worse than the honest if-chain it replaced. Complexity should move into well-named units, not disappear into cleverness.
+- Don't break public APIs or exported signatures without asking.
+- Small functions with clear names > few functions with comments explaining sections.
+- One responsibility per function. If the name needs "and", split.
+
+## Workflow
+
+1. Measure all touched functions, rank by CC descending.
+2. Report hotspots with numbers before touching anything.
+3. Refactor worst first, one function at a time.
+4. Re-measure. Show before/after table: function, CC before, CC after.
+5. Verify: tests pass, behavior unchanged, diff reviewable.
+
+## Output format
+
+End every refactor with:
+
+```
+## Complexity report
+| Function | Before | After |
+|----------|--------|-------|
+| parseOrder | 14 | 4 |
+
+Extracted: validateHeader, resolveDiscount
+Behavior verified: <how>
+```
+
+Keep prose minimal. Numbers and diffs do the talking.

package/assets/skills/five-whys/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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.

package/assets/skills/five-whys/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: five-whys
+description: This skill should be used when the user asks to "find the root cause", "找根因", "为什么会出现这个问题", "why did this happen", "debug this issue", "排查问题", "analyze this bug", "分析这个bug", "what's causing this", "问题出在哪", "dig deeper", "深挖原因", or needs to systematically trace a problem back to its fundamental cause rather than just addressing symptoms.
+version: 0.1.0
+---
+
+# 5-Whys Root Cause Analysis
+
+A systematic technique for drilling down through symptoms to uncover the true root cause of a problem by repeatedly asking "Why?" until the fundamental issue is revealed.
+
+## When to Use This Skill
+
+- Bug investigation where the obvious fix didn't work
+- Production incidents requiring post-mortem analysis
+- Performance problems with unclear origins
+- Recurring issues that keep coming back after "fixes"
+- System failures requiring prevention, not just recovery
+- Any situation where treating symptoms isn't enough
+
+## Core Process
+
+### Phase 1: Define the Problem Clearly
+
+State the problem as a specific, observable fact:
+
+**Good problem statements:**
+- "The API response time increased from 50ms to 500ms"
+- "Users are seeing 500 errors on the checkout page"
+- "The nightly job failed at 3:00 AM"
+
+**Poor problem statements:**
+- "The system is slow" (too vague)
+- "Something is broken" (not specific)
+- "Users are unhappy" (symptom, not problem)
+
+**Problem Statement Template:**
+```
+What: [Specific observable behavior]
+When: [Time/conditions when it occurs]
+Where: [Component/system affected]
+Impact: [Measurable consequence]
+```
+
+### Phase 2: Ask "Why?" Iteratively
+
+For each answer, ask "Why does that happen?" until reaching an actionable root cause:
+
+**The 5-Whys Chain:**
+```
+Problem: [Statement]
+    ↓
+Why 1: [First-level cause]
+    ↓
+Why 2: [Deeper cause]
+    ↓
+Why 3: [Even deeper]
+    ↓
+Why 4: [Approaching root]
+    ↓
+Why 5: [Root cause - actionable]
+```
+
+**Quality Checks for Each "Why":**
+- Is this answer factual and verifiable?
+- Does this explain the previous level?
+- Is there evidence supporting this?
+- Could there be multiple causes at this level?
+
+### Phase 3: Identify the Root Cause
+
+A true root cause has these characteristics:
+
+| Characteristic | Test |
+|----------------|------|
+| **Actionable** | Can we do something about it? |
+| **Preventable** | Would fixing this prevent recurrence? |
+| **Fundamental** | Asking "why" again yields nothing actionable |
+| **Verifiable** | Can we prove this is the cause? |
+
+**Stop Conditions:**
+- Reached a process/policy that can be changed
+- Found a missing control or check
+- Identified a knowledge/training gap
+- Discovered a design flaw
+- Hit a resource constraint decision
+
+### Phase 4: Validate the Chain
+
+Work backwards through the chain:
+
+```
+If [Root Cause] is fixed
+→ Then [Why 4] wouldn't happen
+→ Then [Why 3] wouldn't happen
+→ Then [Why 2] wouldn't happen
+→ Then [Why 1] wouldn't happen
+→ Then [Problem] wouldn't occur
+```
+
+If the chain breaks at any point, revisit that level.
+
+### Phase 5: Define Countermeasures
+
+For the root cause, define:
+
+1. **Immediate fix** - Stop the bleeding
+2. **Preventive measure** - Ensure it never happens again
+3. **Detection mechanism** - Catch it early if prevention fails
+
+## Output Format
+
+```markdown
+## 5-Whys Analysis: [Problem Title]
+
+### Problem Statement
+**What:** [Specific behavior]
+**When:** [Time/conditions]
+**Where:** [Component]
+**Impact:** [Consequence]
+
+### Why Chain
+
+| Level | Question | Answer | Evidence |
+|-------|----------|--------|----------|
+| Why 1 | Why did [problem] occur? | [Answer] | [Evidence] |
+| Why 2 | Why did [Why 1 answer]? | [Answer] | [Evidence] |
+| Why 3 | Why did [Why 2 answer]? | [Answer] | [Evidence] |
+| Why 4 | Why did [Why 3 answer]? | [Answer] | [Evidence] |
+| Why 5 | Why did [Why 4 answer]? | [Answer] | [Evidence] |
+
+### Root Cause
+**Identified cause:** [Statement]
+**Type:** [Process/Design/Knowledge/Resource]
+**Confidence:** [High/Medium/Low]
+
+### Validation
+- [Root cause fixed] → [Why 4 prevented] ✓
+- [Why 4 prevented] → [Why 3 prevented] ✓
+- ... chain validates ...
+
+### Countermeasures
+| Type | Action | Owner | Timeline |
+|------|--------|-------|----------|
+| Immediate | [Action] | [Who] | [When] |
+| Preventive | [Action] | [Who] | [When] |
+| Detection | [Action] | [Who] | [When] |
+```
+
+## Common Pitfalls
+
+### Pitfall 1: Stopping Too Early
+
+**Symptom:** Root cause is still a symptom
+```
+Problem: Server crashed
+Why 1: Out of memory
+→ "Fix: Add more memory" ❌ (Treating symptom)
+
+Continue:
+Why 2: Memory leak in service X
+Why 3: Connection pool not releasing connections
+Why 4: Exception handler not closing connections
+Why 5: No finally block in database code
+→ Fix: Add proper resource cleanup ✓
+```
+
+### Pitfall 2: Blame Instead of Cause
+
+**Wrong:** "Why? → Developer made a mistake"
+**Right:** "Why? → No code review caught the issue"
+**Even better:** "Why? → No automated test for this case"
+
+**Rule:** Focus on process and systems, not individuals.
+
+### Pitfall 3: Single Thread When Multiple Causes Exist
+
+Sometimes problems have multiple contributing factors:
+
+```
+Problem: Deployment failed
+    ↓
+Why 1: Database migration timed out
+    ├─→ Branch A: Why did migration take so long?
+    │   └─→ Table lock held too long
+    │       └─→ Long-running query
+    │           └─→ Missing index
+    │
+    └─→ Branch B: Why is timeout so short?
+        └─→ Default timeout used
+            └─→ No deployment-specific config
+```
+
+### Pitfall 4: Unverified Assumptions
+
+Each "why" should be supported by evidence:
+
+| Level | Answer | Evidence Required |
+|-------|--------|------------------|
+| Why 1 | "Service crashed" | Logs showing crash |
+| Why 2 | "OOM killed" | dmesg/system logs |
+| Why 3 | "Memory leak" | Heap dump analysis |
+| Why 4 | "Unclosed streams" | Code inspection |
+| Why 5 | "Missing finally" | Git blame |
+
+## Integration with Other Tools
+
+| Tool | When to Combine |
+|------|-----------------|
+| **First Principles** | When questioning if the problem definition itself is right |
+| **Hypothesis Testing** | When evidence for a "why" is uncertain |
+| **Pre-mortem** | After fixing, to prevent similar issues |
+| **Trade-off Analysis** | When choosing between countermeasures |
+
+## Boundaries
+
+**Will:**
+- Systematically trace problems to root causes
+- Ensure each level is evidence-based
+- Identify actionable countermeasures
+- Handle multi-branch cause trees
+
+**Will Not:**
+- Stop at blame ("human error")
+- Accept vague answers without evidence
+- Guarantee exactly 5 levels (might be 3, might be 7)
+- Replace detailed debugging when code inspection is needed
+
+## Quick Reference
+
+**The 5-Whys Checklist:**
+- [ ] Problem stated specifically and measurably
+- [ ] Each "why" is factual, not assumed
+- [ ] Evidence supports each level
+- [ ] Root cause is actionable and preventable
+- [ ] Chain validates when traced backwards
+- [ ] Countermeasures address root cause, not symptoms
+- [ ] Process/system focus, not blame
+
+## Additional Resources
+
+### Reference Files
+- **`references/toyota-origins.md`** - History and principles from Toyota Production System
+- **`references/software-patterns.md`** - Common root cause patterns in software
+
+### Example Files
+- **`examples/production-incident.md`** - Complete analysis of a production outage
+- **`examples/performance-regression.md`** - Tracing a performance degradation

package/assets/skills/five-whys/examples/performance-regression.md

@@ -0,0 +1,161 @@
+# Example: Performance Regression - API Latency Increase
+
+A 5-Whys analysis tracing a performance degradation to its root cause.
+
+---
+
+## 5-Whys Analysis: Search API Latency Regression
+
+### Problem Statement
+
+| Field | Details |
+|-------|---------|
+| **What** | Search API p99 latency increased from 200ms to 800ms |
+| **When** | First observed 2024-02-01, after v2.3.0 deployment |
+| **Where** | search-service, all regions |
+| **Duration** | Ongoing until fix deployed |
+| **Impact** | User complaints, 15% drop in search usage |
+
+### Detection Timeline
+
+```
+Feb 1, 10:00 - v2.3.0 deployed to production
+Feb 1, 14:00 - Latency alert fires (p99 > 500ms)
+Feb 1, 14:30 - Investigation begins
+Feb 2, 09:00 - Root cause identified
+Feb 2, 15:00 - Fix deployed, latency returns to normal
+```
+
+---
+
+### Why Chain
+
+| Level | Question | Answer | Evidence |
+|-------|----------|--------|----------|
+| **Why 1** | Why did search API latency increase 4x? | Database queries taking longer | Query timing metrics showed DB time 600ms vs 100ms before |
+| **Why 2** | Why are database queries slower? | Full table scan on products table | EXPLAIN ANALYZE showed Seq Scan instead of Index Scan |
+| **Why 3** | Why is a full table scan happening? | Query predicate changed, doesn't use index | Query plan shows index on `category_id` not being used |
+| **Why 4** | Why doesn't the new query use the index? | New filter uses `LOWER(category_name)` instead of `category_id` | Code diff in v2.3.0 shows the change |
+| **Why 5** | Why was this change made without index? | Developer assumed existing index covered it; no query review | PR #1847 shows no query plan check |
+
+---
+
+### Deeper Investigation
+
+**Why was there no query review in PR #1847?**
+
+| Level | Question | Answer |
+|-------|----------|--------|
+| Why 5a | Why no query review? | Team doesn't have query review checklist |
+| Why 5b | Why no checklist? | Performance wasn't seen as critical for search |
+| Why 5c | Why wasn't it seen as critical? | No SLO defined for search latency |
+
+**Second Root Cause:** No performance SLO → No review process → Regression shipped
+
+---
+
+### Root Causes
+
+**Primary Root Cause:**
+Query changed to use `LOWER(category_name)` for case-insensitive search, but no functional index exists for that expression.
+
+**Category:** Design Gap + Process Gap
+
+**Secondary Root Cause:**
+No query performance review in PR process due to missing latency SLOs.
+
+**Category:** Process Gap
+
+---
+
+### Validation
+
+| Test | Result |
+|------|--------|
+| Add index on `LOWER(category_name)` | Query drops to 80ms ✓ |
+| Deploy to staging with index | p99 returns to 180ms ✓ |
+| Remove index, revert to `category_id` filter | Also fixes issue ✓ |
+
+**Chosen Fix:** Add functional index (preserves case-insensitive feature)
+
+```sql
+CREATE INDEX idx_products_category_name_lower
+ON products (LOWER(category_name));
+```
+
+---
+
+### Why Wasn't This Caught Earlier?
+
+| Stage | Should Have Caught? | Why It Didn't |
+|-------|---------------------|---------------|
+| **Code Review** | Maybe | Reviewer didn't check query plan |
+| **Unit Tests** | No | Tests don't measure performance |
+| **Integration Tests** | Maybe | Test data too small (100 rows vs 10M in prod) |
+| **Staging** | Maybe | Staging has 1M rows, might have caught it |
+| **Canary Deploy** | Yes | But canary wasn't enabled for this service |
+
+---
+
+### Countermeasures
+
+| Priority | Type | Action | Owner | Status |
+|----------|------|--------|-------|--------|
+| **P0** | Immediate | Add functional index | @dba-team | ✅ Done |
+| **P1** | Prevention | Query review checklist for PRs | @tech-lead | ✅ Done |
+| **P1** | Prevention | Enable canary deployments | @sre-team | 🔄 In progress |
+| **P2** | Detection | Query latency alert per endpoint | @sre-team | 📋 Planned |
+| **P2** | Process | Define search latency SLO (p99 < 300ms) | @product | 📋 Planned |
+| **P3** | Testing | Add performance test with prod-like data volume | @qa-team | 📋 Backlog |
+
+---
+
+### Query Review Checklist (Created)
+
+For any PR that modifies database queries:
+
+- [ ] Run `EXPLAIN ANALYZE` on new/modified queries
+- [ ] Verify index usage (no Seq Scan on large tables)
+- [ ] Check estimated rows vs actual rows
+- [ ] Test with production-like data volume
+- [ ] Document expected query performance
+
+---
+
+### Lessons Learned
+
+1. **Case-insensitive search needs functional indexes**
+   - `WHERE LOWER(col) = 'value'` won't use index on `col`
+   - Must create index on `LOWER(col)`
+
+2. **Test data volume matters**
+   - 100 rows: any query is fast
+   - 10M rows: missing index is catastrophic
+
+3. **Canary deployments are essential**
+   - Would have caught 4x latency increase with 1% traffic
+
+4. **SLOs drive process**
+   - Without latency SLO, no one prioritized performance review
+
+---
+
+### 30-Day Follow-up
+
+- [ ] Search p99 consistently < 300ms
+- [ ] Query review checklist being used in PRs
+- [ ] Canary deployment enabled and tested
+- [ ] Performance tests added to CI pipeline
+
+---
+
+## Analysis Quality Assessment
+
+| Criteria | Met? | Notes |
+|----------|------|-------|
+| Problem specific | ✓ | Exact metric, timeframe, deployment |
+| Evidence-based | ✓ | Query plans, metrics, code diffs |
+| Multi-level causes | ✓ | Technical + process root causes |
+| Actionable | ✓ | Index + checklist + canary |
+| Preventable | ✓ | Process changes prevent recurrence |
+| No blame | ✓ | Focus on missing process/tools |

package/assets/skills/five-whys/examples/production-incident.md

@@ -0,0 +1,134 @@
+# Example: Production Incident - Payment Service Outage
+
+A complete 5-Whys analysis of a production payment service failure.
+
+---
+
+## 5-Whys Analysis: Payment Service Outage (2024-01-15)
+
+### Problem Statement
+
+| Field | Details |
+|-------|---------|
+| **What** | Payment API returning 503 errors, all transactions failing |
+| **When** | 2024-01-15, 14:23 UTC, during peak traffic |
+| **Where** | payment-service in production (us-east-1) |
+| **Duration** | 47 minutes |
+| **Impact** | ~$150,000 in failed transactions, 12,000 affected users |
+
+### Timeline
+
+```
+14:23 - First 503 errors appear in monitoring
+14:25 - Alert fires: payment-service error rate > 5%
+14:28 - On-call engineer begins investigation
+14:35 - Identified: all DB connections exhausted
+14:42 - Attempted restart, problem persists
+14:55 - Root cause identified: connection leak
+15:02 - Hotfix deployed
+15:10 - Service fully recovered
+```
+
+---
+
+### Why Chain
+
+| Level | Question | Answer | Evidence |
+|-------|----------|--------|----------|
+| **Why 1** | Why did the payment API return 503 errors? | Database connection pool was exhausted (0/100 available) | Connection pool metrics showed 100/100 in use |
+| **Why 2** | Why was the connection pool exhausted? | Connections were being acquired but not released | Connection age histogram showed connections held for hours |
+| **Why 3** | Why were connections not being released? | Exception thrown before connection.close() in refund handler | Stack trace in logs showed exception at line 142 |
+| **Why 4** | Why did the exception prevent connection close? | No try-finally block; close() only in happy path | Code inspection of RefundHandler.java |
+| **Why 5** | Why was there no try-finally block? | Code copied from old service that used auto-commit (no explicit close needed) | Git blame showed copy-paste from legacy service |
+
+---
+
+### Root Cause
+
+**Identified Cause:** Connection handling code was copied from a legacy service that used auto-commit mode (where connections auto-close). The new service uses manual transactions, requiring explicit close(), but the code pattern wasn't updated.
+
+**Category:** Design Gap (incorrect pattern application)
+
+**Confidence:** High (reproduced in staging)
+
+---
+
+### Multi-Branch Analysis
+
+The outage had a contributing factor that made it worse:
+
+```
+Primary Branch (Root Cause):
+Connection leak in refund handler
+    ↓
+Pool exhausted
+
+Contributing Branch (Made it worse):
+Why wasn't this caught earlier?
+    ↓
+Why 1: No connection pool monitoring alert
+    ↓
+Why 2: Monitoring dashboard existed but no alert threshold
+    ↓
+Why 3: Alert was in backlog, not prioritized
+    ↓
+Why 4: No SLO defined for connection pool utilization
+```
+
+---
+
+### Validation
+
+Testing the causal chain backwards:
+
+| If... | Then... | Validates? |
+|-------|---------|------------|
+| Try-finally added to RefundHandler | Connections always released | ✓ Tested in staging |
+| Connections always released | Pool never exhausts | ✓ Load test confirmed |
+| Pool never exhausts | No 503 errors from DB | ✓ Verified |
+| No 503 errors | Payment service stays healthy | ✓ |
+
+---
+
+### Countermeasures
+
+| Priority | Type | Action | Owner | Status |
+|----------|------|--------|-------|--------|
+| **P0** | Immediate | Add try-finally to RefundHandler | @dev-alice | ✅ Done |
+| **P0** | Immediate | Audit all DB handlers for same pattern | @dev-bob | ✅ Done (found 2 more) |
+| **P1** | Prevention | Add connection pool alert at 80% | @sre-carol | ✅ Done |
+| **P1** | Prevention | Linter rule: require try-finally for DB connections | @dev-alice | 🔄 In progress |
+| **P2** | Detection | Connection age histogram alert (>5min) | @sre-carol | 📋 Planned |
+| **P2** | Process | Code review checklist: resource cleanup | @tech-lead | 📋 Planned |
+
+---
+
+### Lessons Learned
+
+1. **Code copying is risky** - Patterns from one context may not apply in another
+2. **Resource cleanup needs defense in depth** - Linting + review + monitoring
+3. **Monitoring without alerts is incomplete** - Dashboards don't page on-call
+4. **Connection pools need visibility** - Should be first-class metric
+
+---
+
+### Follow-up Verification
+
+**30-day check:**
+- [ ] No connection pool exhaustion incidents
+- [ ] Linter rule catching violations in PRs
+- [ ] Connection age alerts working (tested with chaos engineering)
+
+---
+
+## Analysis Quality Assessment
+
+| Criteria | Met? | Notes |
+|----------|------|-------|
+| Problem specific and measurable | ✓ | Exact error, time, impact quantified |
+| Each "why" has evidence | ✓ | Logs, metrics, code inspection |
+| Root cause is actionable | ✓ | Code change fixes it |
+| Root cause is preventable | ✓ | Linter + review prevents recurrence |
+| Chain validates backwards | ✓ | Tested in staging |
+| No blame, only process | ✓ | Focused on missing patterns/tools |
+| Countermeasures assigned | ✓ | Owners and timelines set |