@musashishao/agent-kit 1.0.0 → 1.1.0

package/.agent/skills/problem-solving/SKILL.md

@@ -0,0 +1,556 @@
+---
+name: problem-solving
+description: Advanced problem-solving frameworks for complex challenges. 6 techniques for when you're stuck, need creative solutions, or want to think differently.
+allowed-tools: Read, Write, Edit
+---
+
+# Problem-Solving Frameworks
+
+> Think differently. Solve creatively. Break through blocks.
+
+## 📋 Quick Reference
+
+| Framework | When to Use | Key Question |
+|-----------|-------------|--------------|
+| [When Stuck](#1-when-stuck-dispatcher) | Don't know which technique | "What type of stuck am I?" |
+| [Inversion](#2-inversion-exercise) | Assumptions blocking you | "What if the opposite were true?" |
+| [Collision Zone](#3-collision-zone-thinking) | Need creative breakthrough | "What if we treated X like Y?" |
+| [Scale Game](#4-scale-game) | Hidden constraints | "What happens at 1000x?" |
+| [Pattern Recognition](#5-meta-pattern-recognition) | Complex systems | "What patterns appear across domains?" |
+| [Simplification](#6-simplification-cascades) | Overcomplicated solution | "What one insight eliminates everything?" |
+
+---
+
+## 1. When Stuck (Dispatcher)
+
+> Use this first to route to the right technique.
+
+### Stuck Type Assessment
+
+```
+What type of stuck are you?
+
+┌─────────────────────────────────────────────────────────────┐
+│ 1. "I don't know where to start"                           │
+│    → Use INVERSION: Start from the end, work backwards     │
+├─────────────────────────────────────────────────────────────┤
+│ 2. "I've tried everything, nothing works"                  │
+│    → Use COLLISION ZONE: Combine unrelated concepts        │
+├─────────────────────────────────────────────────────────────┤
+│ 3. "The solution is too complex"                           │
+│    → Use SIMPLIFICATION: Find the one insight that changes │
+│      everything                                             │
+├─────────────────────────────────────────────────────────────┤
+│ 4. "I can't see the full picture"                          │
+│    → Use PATTERN RECOGNITION: Find patterns across domains │
+├─────────────────────────────────────────────────────────────┤
+│ 5. "My assumptions might be wrong"                         │
+│    → Use INVERSION: Flip every assumption                  │
+├─────────────────────────────────────────────────────────────┤
+│ 6. "I need to validate my approach"                        │
+│    → Use SCALE GAME: Test at extreme scales                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Quick Unstuck Protocol
+
+1. **Name the block:** Write one sentence about why you're stuck
+2. **Categorize:** Match to stuck type above
+3. **Apply framework:** Use the recommended technique
+4. **Iterate:** If still stuck, try the next framework
+
+---
+
+## 2. Inversion Exercise
+
+> "What if the opposite were true?"
+
+### When to Use
+- Assumptions are blocking progress
+- Conventional approaches have failed
+- Need fresh perspective on old problem
+
+### The Process
+
+#### Step 1: List Your Assumptions
+```
+Problem: Users aren't completing checkout
+
+Assumptions:
+- Users want to complete checkout
+- The checkout flow is too long
+- Users need more payment options
+- Price is the main barrier
+```
+
+#### Step 2: Invert Each Assumption
+```
+Inversions:
+- What if users DON'T want to complete checkout?
+  → Are we pushing them too early?
+  → Is cart a wishlist, not purchase intent?
+
+- What if checkout is TOO SHORT?
+  → Missing trust signals?
+  → No confirmation they're buying the right thing?
+
+- What if users want FEWER options?
+  → Decision paralysis from too many choices?
+
+- What if price ISN'T the barrier?
+  → Shipping? Trust? Uncertainty about product?
+```
+
+#### Step 3: Explore Promising Inversions
+```
+Most promising inversion:
+"Cart is a wishlist, not purchase intent"
+
+New approach:
+- Add "Save for Later" prominently
+- Only push checkout when browsing pattern shows intent
+- Send reminder emails for wishlisted items
+```
+
+### Inversion Templates
+
+| Original Assumption | Inversion Question |
+|-------------------|-------------------|
+| Users need X feature | What if X makes things worse? |
+| This is a tech problem | What if this is a people problem? |
+| More data will help | What if we have too much data? |
+| Speed is important | What if slow is actually better? |
+| Users want control | What if users want less decisions? |
+
+---
+
+## 3. Collision Zone Thinking
+
+> "What if we treated X like Y?"
+
+### When to Use
+- Need creative breakthrough
+- Incremental improvements aren't enough
+- Looking for innovation, not optimization
+
+### The Process
+
+#### Step 1: Define Your Problem Space
+```
+Problem: Onboarding new developers is slow (3 weeks)
+Current solutions: Documentation, pairing, training
+```
+
+#### Step 2: Pick Unrelated Domains
+```
+Random domains:
+- Video games
+- Restaurant kitchens
+- Airport security
+- Theme parks
+```
+
+#### Step 3: Force Collisions
+```
+"What if onboarding was like a VIDEO GAME?"
+├── Levels: Progressive complexity, unlock new areas
+├── Quests: Small, clear objectives with rewards
+├── XP System: Track progress, celebrate milestones
+├── NPCs: Bot guides that answer questions
+└── Multiplayer: Collaborative challenges with team
+
+"What if onboarding was like AIRPORT SECURITY?"
+├── Clear checkpoints: Must pass each before next
+├── Fast lanes: Skip if you have experience
+├── Screening: Assess skills upfront, personalize path
+└── Pre-check: Pre-work before first day
+```
+
+#### Step 4: Extract Insights
+```
+Winning insight from Video Games:
+→ Create "Developer Quest" system
+   - Day 1: Complete 3 quests (setup, first commit, code review)
+   - Week 1: Earn "Backend Badge" by completing module
+   - Instant feedback on progress
+   - Leaderboard for fun competition
+```
+
+### Collision Prompt Templates
+
+```
+"What if [YOUR PROBLEM] worked like [RANDOM DOMAIN]?"
+
+Fill in:
+- What if user auth worked like a hotel check-in?
+- What if code review worked like restaurant quality control?
+- What if deployment worked like a rocket launch?
+- What if bug fixing worked like detective work?
+- What if documentation worked like a museum tour?
+```
+
+---
+
+## 4. Scale Game
+
+> "What happens at 1000x? At 0.001x?"
+
+### When to Use
+- Need to stress-test assumptions
+- Want to find hidden constraints
+- Validating architecture decisions
+- Looking for edge cases
+
+### The Process
+
+#### Step 1: Identify Variables to Scale
+```
+System: E-commerce checkout
+
+Scalable variables:
+- Number of users
+- Cart size
+- Transaction frequency
+- Product catalog size
+- Geographic distribution
+```
+
+#### Step 2: Scale Up (1000x)
+```
+Current: 100 orders/day
+At 1000x: 100,000 orders/day
+
+What breaks?
+├── Database: Single Postgres won't handle
+├── Inventory: Race conditions on popular items
+├── Payments: Gateway rate limits hit
+├── Emails: Confirmation emails get rate limited
+├── Support: 1000x support tickets
+
+What's revealed?
+→ We have no caching strategy
+→ Inventory system is synchronous
+→ No queuing for async operations
+```
+
+#### Step 3: Scale Down (0.001x)
+```
+At 0.001x: 0.1 orders/day (1 order every 10 days)
+
+What's revealed?
+├── Session timeouts: Cart expires before purchase
+├── Stale data: Prices/availability change
+├── Engagement: Users forget they have cart
+├── Economics: Fixed costs don't scale down
+
+Insights:
+→ Need re-engagement for long consideration cycles
+→ "Save cart" feature becomes critical
+→ Price guarantee for saved items
+```
+
+#### Step 4: Extreme Dimensions
+```
+What if checkout took 1 SECOND total?
+→ Must pre-authorize everything
+→ One-click only works with saved info
+→ No real-time inventory check possible
+
+What if checkout took 1 WEEK?
+→ Multi-session persistence required
+→ Approval workflows (enterprise sales)
+→ Price/availability guarantees needed
+→ Reminders and notifications
+```
+
+### Scale Game Template
+
+| Variable | Current | 1000x | 0.001x | Insight |
+|----------|---------|-------|--------|---------|
+| Users | 1K | 1M | 1 | ? |
+| Requests/sec | 10 | 10K | 0.01 | ? |
+| Data size | 1GB | 1TB | 1MB | ? |
+| Latency | 100ms | 100s | 0.1ms | ? |
+
+---
+
+## 5. Meta-Pattern Recognition
+
+> "What patterns appear across 3+ domains?"
+
+### When to Use
+- Solving a problem that exists in many fields
+- Looking for universal principles
+- Want to leverage cross-domain wisdom
+
+### The Process
+
+#### Step 1: Identify the Core Challenge
+```
+Core challenge: Managing technical debt
+```
+
+#### Step 2: Find 3+ Domains with Similar Challenge
+```
+Similar challenges in other domains:
+1. Physical infrastructure: Deferred building maintenance
+2. Personal health: Ignored minor health issues
+3. Finance: Compound interest on debt
+4. Ecology: Environmental degradation
+```
+
+#### Step 3: Extract Patterns Across All
+```
+Pattern Analysis:
+
+Domain 1 - Building maintenance:
+- Small issues become structural problems
+- Prevention 10x cheaper than repair
+- Regular inspection catch early
+
+Domain 2 - Health:
+- Minor symptoms become chronic conditions
+- Regular checkups prevent major issues
+- "Debt" accumulates invisibly
+
+Domain 3 - Finance:
+- Interest compounds exponentially
+- Minimum payments don't reduce principal
+- Snowball method: smallest first
+
+Domain 4 - Ecology:
+- Degradation invisible until tipping point
+- Restoration harder than prevention
+- Systems interconnected
+
+UNIVERSAL PATTERNS:
+├── Exponential growth when ignored
+├── Prevention << Cure (10x or more)
+├── Invisible accumulation until crisis
+├── Regular inspection is key
+└── Interconnection causes cascades
+```
+
+#### Step 4: Apply Universal Patterns
+```
+Apply to tech debt:
+
+1. Exponential growth
+   → Track debt age, older = higher priority
+
+2. Prevention << Cure
+   → Code review standards prevent debt
+   → "Boy scout rule": Leave code cleaner
+
+3. Invisible accumulation
+   → Make debt visible: Dashboard, metrics
+   → Regular "debt review" meetings
+
+4. Regular inspection
+   → Automated code quality checks
+   → Quarterly debt audits
+
+5. Cascading effects
+   → Map dependencies
+   → Prioritize shared code debt
+```
+
+### Pattern Template
+
+| Domain 1 | Domain 2 | Domain 3 | UNIVERSAL PATTERN |
+|----------|----------|----------|-------------------|
+| Observation A1 | Observation A2 | Observation A3 | → Pattern A |
+| Observation B1 | Observation B2 | Observation B3 | → Pattern B |
+
+---
+
+## 6. Simplification Cascades
+
+> "What one insight eliminates multiple components?"
+
+### When to Use
+- Solution feels overcomplicated
+- Too many edge cases
+- Architecture is getting messy
+- Looking for elegant solutions
+
+### The Process
+
+#### Step 1: Map Current Complexity
+```
+Current feature: User permissions system
+
+Components:
+├── Role definitions (5 files)
+├── Permission checks (23 places)
+├── Role assignment UI (3 screens)
+├── Role inheritance logic
+├── Permission cache
+├── Audit logging
+└── Admin override system
+```
+
+#### Step 2: Ask "What If" Questions
+```
+Simplification questions:
+
+1. "What if there were only 2 roles?"
+   - Most systems really need: Admin vs Member
+   - 90% of role complexity is unused
+   
+2. "What if permissions were at the resource level?"
+   - Instead of user → role → permission
+   - Just user → resource access
+   
+3. "What if we removed inheritance?"
+   - Explicit > Implicit
+   - Copy permissions instead of inheriting
+```
+
+#### Step 3: Find Cascade Effects
+```
+Winning insight: "Only 2 roles needed"
+
+Cascade effect:
+├── ELIMINATE: Role inheritance (not needed)
+├── ELIMINATE: Complex permission matrix
+├── SIMPLIFY: Role UI (dropdown instead of checkboxes)
+├── SIMPLIFY: Permission checks (isAdmin? helper)
+├── ELIMINATE: Most audit complexity
+└── KEEP: Resource-level exceptions only
+
+Complexity reduction: 7 components → 3
+Code reduction: ~60%
+Maintenance reduction: ~80%
+```
+
+#### Step 4: Validate Simplification
+```
+Validation questions:
+- Does this cover 90% of use cases? → Yes
+- What's lost? → Granular permission control
+- Can we add back if needed? → Yes, progressively
+- What's the migration path? → Map existing to 2 roles
+```
+
+### Simplification Patterns
+
+| Complex Approach | Simple Alternative |
+|-----------------|-------------------|
+| Multiple inheritance | Composition/copying |
+| Flexible schema | Fixed schema + extensions table |
+| Real-time everything | Eventually consistent + refresh |
+| Custom solution | Off-the-shelf + workarounds |
+| Prevent all edge cases | Handle, log, and monitor |
+
+---
+
+## 7. Combining Frameworks
+
+### Sequential Combination
+
+```
+Problem: Our API is too slow
+
+1. INVERSION: "What if slow is okay?"
+   → Insight: Users can tolerate 3s, not 300ms
+
+2. SCALE GAME: "What at 1000x requests?"
+   → Insight: Caching solves 90% of requests
+
+3. SIMPLIFICATION: "What one change helps most?"
+   → Insight: Add CDN, eliminate 10 optimization tickets
+
+Final solution: CDN + Accept 3s for cache misses
+Effort: 1 day instead of 2 weeks
+```
+
+### Parallel Combination
+
+```
+Problem: User retention is dropping
+
+Run all frameworks simultaneously:
+
+INVERSION: "What if users SHOULD leave?"
+→ Maybe we're attracting wrong users
+
+COLLISION: "What if our app was like a gym?"
+→ People sign up but don't come; need habit triggers
+
+SCALE: "What at 1 user?"
+→ App feels empty without community
+
+PATTERNS: "Retention in games, social, fitness"
+→ Progress tracking, social proof, streaks
+
+SIMPLIFICATION: "One feature for retention?"
+→ Daily streak with reward = 40% retention boost
+```
+
+---
+
+## 8. Quick Reference Card
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              PROBLEM-SOLVING QUICK REFERENCE                │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  STUCK? → Ask: "What type of stuck am I?"                  │
+│                                                             │
+│  INVERSION                                                  │
+│  → Flip assumptions                                         │
+│  → "What if the opposite were true?"                       │
+│                                                             │
+│  COLLISION ZONE                                             │
+│  → Force unrelated concepts together                        │
+│  → "What if X worked like Y?"                              │
+│                                                             │
+│  SCALE GAME                                                 │
+│  → Test at 1000x and 0.001x                                │
+│  → "What breaks? What's revealed?"                         │
+│                                                             │
+│  PATTERN RECOGNITION                                        │
+│  → Find patterns in 3+ domains                             │
+│  → "What universal principle applies?"                      │
+│                                                             │
+│  SIMPLIFICATION                                             │
+│  → Find the one insight that changes everything            │
+│  → "What eliminates multiple components?"                   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 9. Exercise: Practice Problem
+
+### Problem
+> Our CI/CD pipeline takes 45 minutes. Developers complain it's too slow.
+
+### Apply Each Framework
+
+**INVERSION:** What if 45 minutes is fine?
+- Maybe the issue is unpredictable time, not length
+- What if we ran builds in background?
+
+**COLLISION:** What if CI was like a restaurant kitchen?
+- Prep (tests) before service (deploy)
+- Parallel stations (parallel jobs)
+- Priority orders (urgent hotfixes)
+
+**SCALE:** At 1000x commits/day?
+- Queue would be infinite
+- Need: Deduplication, priority, caching
+
+**PATTERNS:** Build systems, cooking, manufacturing
+- All use: Caching, parallelization, incremental work
+- Toyota: Do smallest unit of work possible
+
+**SIMPLIFICATION:** One change for 80% improvement?
+- Cache unchanged steps = 30min → 10min
+
+---
+
+> **Remember:** These frameworks are tools, not rules. Use them when stuck, combine them for complex problems, and develop your own variations. The goal is better thinking, not following a checklist.