cokit-cli 1.0.9 → 1.2.2

package/skills/{ck-problem-solving → problem-solving}/references/scale-game.md

@@ -1,95 +1,95 @@
-# Scale Game
-
-Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths hidden at normal scales.
-
-## Core Principle
-
-**Extremes expose fundamentals.** What works at one scale fails at another.
-
-## When to Use
-
-| Symptom | Action |
-|---------|--------|
-| "Should scale fine" (without testing) | Test at extremes |
-| Uncertain about production behavior | Scale up 1000x |
-| Edge cases unclear | Test minimum and maximum |
-| Architecture validation needed | Extreme testing |
-
-## Quick Reference
-
-| Scale Dimension | Test At Extremes | What It Reveals |
-|-----------------|------------------|-----------------|
-| **Volume** | 1 item vs 1B items | Algorithmic complexity limits |
-| **Speed** | Instant vs 1 year | Async requirements, caching needs |
-| **Users** | 1 user vs 1B users | Concurrency issues, resource limits |
-| **Duration** | Milliseconds vs years | Memory leaks, state growth |
-| **Failure rate** | Never fails vs always fails | Error handling adequacy |
-
-## Process
-
-1. **Pick dimension** - What could vary extremely?
-2. **Test minimum** - What if 1000x smaller/faster/fewer?
-3. **Test maximum** - What if 1000x bigger/slower/more?
-4. **Note what breaks** - Where do limits appear?
-5. **Note what survives** - What's fundamentally sound?
-6. **Design for reality** - Use insights to validate architecture
-
-## Detailed Examples
-
-### Example 1: Error Handling
-- **Normal scale:** "Handle errors when they occur" works fine
-- **At 1B scale:** Error volume overwhelms logging, crashes system
-- **Reveals:** Need to make errors impossible (type systems) or expect them (chaos engineering)
-- **Action:** Design error handling for volume, not just occurrence
-
-### Example 2: Synchronous APIs
-- **Normal scale:** Direct function calls work, < 100ms latency
-- **At global scale:** Network latency makes synchronous unusable (200-500ms)
-- **Reveals:** Async/messaging becomes survival requirement, not optimization
-- **Action:** Design async-first from start
-
-### Example 3: In-Memory State
-- **Normal duration:** Works for hours/days in development
-- **At years:** Memory grows unbounded, eventual crash (weeks → months → years)
-- **Reveals:** Need persistence or periodic cleanup, can't rely on memory forever
-- **Action:** Design for stateless or externalized state
-
-### Example 4: Single vs Million Users
-- **Normal scale:** Session in memory works for 100 users
-- **At 1M scale:** Memory exhausted, server crashes
-- **Reveals:** Need distributed session store (Redis, database)
-- **Action:** Design for horizontal scaling from start
-
-## Both Directions Matter
-
-**Test smaller too:**
-- What if only 1 user? Does complexity make sense?
-- What if only 10 items? Is optimization premature?
-- What if instant response? What becomes unnecessary?
-
-Often reveals over-engineering or premature optimization.
-
-## Red Flags
-
-You need scale game when:
-- "It works in dev" (but will it work in production?)
-- No idea where limits are
-- "Should scale fine" (without evidence)
-- Surprised by production behavior
-- Architecture feels arbitrary
-
-## Success Metrics
-
-After scale game, you should know:
-- Where system breaks (exact limits)
-- What survives (fundamentally sound parts)
-- What needs redesign (scale-dependent)
-- Production readiness (validated architecture)
-
-## Remember
-
-- Extremes reveal fundamentals hidden at normal scales
-- What works at one scale fails at another
-- Test BOTH directions (bigger AND smaller)
-- Use insights to validate architecture early
-- Don't guess - test at extremes
+# Scale Game
+
+Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths hidden at normal scales.
+
+## Core Principle
+
+**Extremes expose fundamentals.** What works at one scale fails at another.
+
+## When to Use
+
+| Symptom | Action |
+|---------|--------|
+| "Should scale fine" (without testing) | Test at extremes |
+| Uncertain about production behavior | Scale up 1000x |
+| Edge cases unclear | Test minimum and maximum |
+| Architecture validation needed | Extreme testing |
+
+## Quick Reference
+
+| Scale Dimension | Test At Extremes | What It Reveals |
+|-----------------|------------------|-----------------|
+| **Volume** | 1 item vs 1B items | Algorithmic complexity limits |
+| **Speed** | Instant vs 1 year | Async requirements, caching needs |
+| **Users** | 1 user vs 1B users | Concurrency issues, resource limits |
+| **Duration** | Milliseconds vs years | Memory leaks, state growth |
+| **Failure rate** | Never fails vs always fails | Error handling adequacy |
+
+## Process
+
+1. **Pick dimension** - What could vary extremely?
+2. **Test minimum** - What if 1000x smaller/faster/fewer?
+3. **Test maximum** - What if 1000x bigger/slower/more?
+4. **Note what breaks** - Where do limits appear?
+5. **Note what survives** - What's fundamentally sound?
+6. **Design for reality** - Use insights to validate architecture
+
+## Detailed Examples
+
+### Example 1: Error Handling
+- **Normal scale:** "Handle errors when they occur" works fine
+- **At 1B scale:** Error volume overwhelms logging, crashes system
+- **Reveals:** Need to make errors impossible (type systems) or expect them (chaos engineering)
+- **Action:** Design error handling for volume, not just occurrence
+
+### Example 2: Synchronous APIs
+- **Normal scale:** Direct function calls work, < 100ms latency
+- **At global scale:** Network latency makes synchronous unusable (200-500ms)
+- **Reveals:** Async/messaging becomes survival requirement, not optimization
+- **Action:** Design async-first from start
+
+### Example 3: In-Memory State
+- **Normal duration:** Works for hours/days in development
+- **At years:** Memory grows unbounded, eventual crash (weeks → months → years)
+- **Reveals:** Need persistence or periodic cleanup, can't rely on memory forever
+- **Action:** Design for stateless or externalized state
+
+### Example 4: Single vs Million Users
+- **Normal scale:** Session in memory works for 100 users
+- **At 1M scale:** Memory exhausted, server crashes
+- **Reveals:** Need distributed session store (Redis, database)
+- **Action:** Design for horizontal scaling from start
+
+## Both Directions Matter
+
+**Test smaller too:**
+- What if only 1 user? Does complexity make sense?
+- What if only 10 items? Is optimization premature?
+- What if instant response? What becomes unnecessary?
+
+Often reveals over-engineering or premature optimization.
+
+## Red Flags
+
+You need scale game when:
+- "It works in dev" (but will it work in production?)
+- No idea where limits are
+- "Should scale fine" (without evidence)
+- Surprised by production behavior
+- Architecture feels arbitrary
+
+## Success Metrics
+
+After scale game, you should know:
+- Where system breaks (exact limits)
+- What survives (fundamentally sound parts)
+- What needs redesign (scale-dependent)
+- Production readiness (validated architecture)
+
+## Remember
+
+- Extremes reveal fundamentals hidden at normal scales
+- What works at one scale fails at another
+- Test BOTH directions (bigger AND smaller)
+- Use insights to validate architecture early
+- Don't guess - test at extremes

package/skills/{ck-problem-solving → problem-solving}/references/simplification-cascades.md

@@ -1,80 +1,80 @@
-# Simplification Cascades
-
-Find one insight eliminating multiple components. "If this is true, we don't need X, Y, Z."
-
-## Core Principle
-
-**Everything is a special case of...** collapses complexity dramatically.
-
-One powerful abstraction > ten clever hacks.
-
-## When to Use
-
-| Symptom | Action |
-|---------|--------|
-| Same thing implemented 5+ ways | Abstract the common pattern |
-| Growing special case list | Find the general case |
-| Complex rules with exceptions | Find rule with no exceptions |
-| Excessive config options | Find defaults working for 95% |
-
-## The Pattern
-
-**Look for:**
-- Multiple implementations of similar concepts
-- Special case handling everywhere
-- "We need to handle A, B, C, D differently..."
-- Complex rules with many exceptions
-
-**Ask:** "What if they're all the same thing underneath?"
-
-## Examples
-
-### Example 1: Stream Abstraction
-- **Before:** Separate handlers for batch/real-time/file/network data
-- **Insight:** "All inputs are streams - just different sources"
-- **After:** One stream processor, multiple stream sources
-- **Eliminated:** 4 separate implementations
-
-### Example 2: Resource Governance
-- **Before:** Session tracking, rate limiting, file validation, connection pooling (all separate)
-- **Insight:** "All are per-entity resource limits"
-- **After:** One ResourceGovernor with 4 resource types
-- **Eliminated:** 4 custom enforcement systems
-
-### Example 3: Immutability
-- **Before:** Defensive copying, locking, cache invalidation, temporal coupling
-- **Insight:** "Treat everything as immutable data + transformations"
-- **After:** Functional programming patterns
-- **Eliminated:** Entire classes of synchronization problems
-
-## Process
-
-1. **List variations** - What's implemented multiple ways?
-2. **Find essence** - What's the same underneath?
-3. **Extract abstraction** - What's the domain-independent pattern?
-4. **Test fit** - Do all cases fit cleanly?
-5. **Measure cascade** - How many things become unnecessary?
-
-## Red Flags
-
-Signs you're missing a cascade:
-- "Just need to add one more case..." (repeating forever)
-- "These are similar but different" (maybe they're the same?)
-- Refactoring feels like whack-a-mole (fix one, break another)
-- Growing configuration file
-- "Don't touch that, it's complicated" (complexity hiding pattern)
-
-## Success Metrics
-
-- **10x wins, not 10% improvements**
-- Measure in "how many things can we delete?"
-- Lines of code removed > lines added
-- Configuration options eliminated
-- Special cases unified
-
-## Remember
-
-- The pattern is usually already there, just needs recognition
-- Valid cascades feel obvious in retrospect
-- Test with "can this handle all existing cases?"
-- Document the insight for future reference
+# Simplification Cascades
+
+Find one insight eliminating multiple components. "If this is true, we don't need X, Y, Z."
+
+## Core Principle
+
+**Everything is a special case of...** collapses complexity dramatically.
+
+One powerful abstraction > ten clever hacks.
+
+## When to Use
+
+| Symptom | Action |
+|---------|--------|
+| Same thing implemented 5+ ways | Abstract the common pattern |
+| Growing special case list | Find the general case |
+| Complex rules with exceptions | Find rule with no exceptions |
+| Excessive config options | Find defaults working for 95% |
+
+## The Pattern
+
+**Look for:**
+- Multiple implementations of similar concepts
+- Special case handling everywhere
+- "We need to handle A, B, C, D differently..."
+- Complex rules with many exceptions
+
+**Ask:** "What if they're all the same thing underneath?"
+
+## Examples
+
+### Example 1: Stream Abstraction
+- **Before:** Separate handlers for batch/real-time/file/network data
+- **Insight:** "All inputs are streams - just different sources"
+- **After:** One stream processor, multiple stream sources
+- **Eliminated:** 4 separate implementations
+
+### Example 2: Resource Governance
+- **Before:** Session tracking, rate limiting, file validation, connection pooling (all separate)
+- **Insight:** "All are per-entity resource limits"
+- **After:** One ResourceGovernor with 4 resource types
+- **Eliminated:** 4 custom enforcement systems
+
+### Example 3: Immutability
+- **Before:** Defensive copying, locking, cache invalidation, temporal coupling
+- **Insight:** "Treat everything as immutable data + transformations"
+- **After:** Functional programming patterns
+- **Eliminated:** Entire classes of synchronization problems
+
+## Process
+
+1. **List variations** - What's implemented multiple ways?
+2. **Find essence** - What's the same underneath?
+3. **Extract abstraction** - What's the domain-independent pattern?
+4. **Test fit** - Do all cases fit cleanly?
+5. **Measure cascade** - How many things become unnecessary?
+
+## Red Flags
+
+Signs you're missing a cascade:
+- "Just need to add one more case..." (repeating forever)
+- "These are similar but different" (maybe they're the same?)
+- Refactoring feels like whack-a-mole (fix one, break another)
+- Growing configuration file
+- "Don't touch that, it's complicated" (complexity hiding pattern)
+
+## Success Metrics
+
+- **10x wins, not 10% improvements**
+- Measure in "how many things can we delete?"
+- Lines of code removed > lines added
+- Configuration options eliminated
+- Special cases unified
+
+## Remember
+
+- The pattern is usually already there, just needs recognition
+- Valid cascades feel obvious in retrospect
+- Test with "can this handle all existing cases?"
+- Document the insight for future reference

package/{templates/repo/.github/skills/ck-problem-solving → skills/problem-solving}/references/when-stuck.md

@@ -1,72 +1,72 @@
-# When Stuck - Problem-Solving Dispatch
-
-Different stuck-types need different techniques. Match stuck-symptom to technique.
-
-## Dispatch Flowchart
-
-```
-YOU'RE STUCK
-│
-├─ Complexity spiraling? Same thing 5+ ways? Growing special cases?
-│  └─→ USE: Simplification Cascades
-│
-├─ Can't find fitting approach? Conventional solutions inadequate?
-│  └─→ USE: Collision-Zone Thinking
-│
-├─ Same issue different places? Reinventing wheels? Feels familiar?
-│  └─→ USE: Meta-Pattern Recognition
-│
-├─ Solution feels forced? "Must be done this way"? Stuck on assumptions?
-│  └─→ USE: Inversion Exercise
-│
-├─ Will this work at production? Edge cases unclear? Unsure of limits?
-│  └─→ USE: Scale Game
-│
-└─ Code broken? Wrong behavior? Test failing?
-   └─→ USE: Debugging skill (systematic-debugging)
-```
-
-## Stuck-Type → Technique Map
-
-| How You're Stuck | Symptom Details | Use This |
-|------------------|-----------------|----------|
-| **Complexity spiraling** | Same thing 5+ ways, growing special cases, excessive if/else | simplification-cascades.md |
-| **Need innovation** | Conventional inadequate, can't find fitting approach, need breakthrough | collision-zone-thinking.md |
-| **Recurring patterns** | Same issue different places, reinventing wheels, déjà vu feeling | meta-pattern-recognition.md |
-| **Forced by assumptions** | "Must be done this way", can't question premise, forced solution | inversion-exercise.md |
-| **Scale uncertainty** | Production unclear, edge cases unknown, unsure of limits | scale-game.md |
-| **Code broken** | Wrong behavior, test failing, unexpected output | debugging skill |
-
-## Process
-
-1. **Identify stuck-type** - What symptom matches above?
-2. **Load that technique** - Read the specific reference file
-3. **Apply technique** - Follow its process
-4. **Document attempt** - What worked/failed?
-5. **If still stuck** - Try different technique or combine
-
-## Combining Techniques
-
-Some problems need multiple techniques:
-
-- **Simplification + Meta-pattern** - Find pattern → simplify all instances
-- **Collision + Inversion** - Force metaphor → invert assumptions
-- **Scale + Simplification** - Test extremes → reveal what to eliminate
-- **Meta-pattern + Scale** - Universal pattern → test at extremes
-
-## When Nothing Works
-
-If no technique helps:
-1. **Reframe problem** - Are you solving the right problem?
-2. **Get fresh perspective** - Explain to someone else
-3. **Take break** - Distance often reveals solution
-4. **Simplify scope** - Solve smaller version first
-5. **Question constraints** - Are they real or assumed?
-
-## Remember
-
-- Match symptom to technique
-- One technique at a time
-- Combine if first doesn't work
-- Document what you tried
-- Not stuck forever, just temporarily
+# When Stuck - Problem-Solving Dispatch
+
+Different stuck-types need different techniques. Match stuck-symptom to technique.
+
+## Dispatch Flowchart
+
+```
+YOU'RE STUCK
+│
+├─ Complexity spiraling? Same thing 5+ ways? Growing special cases?
+│  └─→ USE: Simplification Cascades
+│
+├─ Can't find fitting approach? Conventional solutions inadequate?
+│  └─→ USE: Collision-Zone Thinking
+│
+├─ Same issue different places? Reinventing wheels? Feels familiar?
+│  └─→ USE: Meta-Pattern Recognition
+│
+├─ Solution feels forced? "Must be done this way"? Stuck on assumptions?
+│  └─→ USE: Inversion Exercise
+│
+├─ Will this work at production? Edge cases unclear? Unsure of limits?
+│  └─→ USE: Scale Game
+│
+└─ Code broken? Wrong behavior? Test failing?
+   └─→ USE: Debugging skill (systematic-debugging)
+```
+
+## Stuck-Type → Technique Map
+
+| How You're Stuck | Symptom Details | Use This |
+|------------------|-----------------|----------|
+| **Complexity spiraling** | Same thing 5+ ways, growing special cases, excessive if/else | simplification-cascades.md |
+| **Need innovation** | Conventional inadequate, can't find fitting approach, need breakthrough | collision-zone-thinking.md |
+| **Recurring patterns** | Same issue different places, reinventing wheels, déjà vu feeling | meta-pattern-recognition.md |
+| **Forced by assumptions** | "Must be done this way", can't question premise, forced solution | inversion-exercise.md |
+| **Scale uncertainty** | Production unclear, edge cases unknown, unsure of limits | scale-game.md |
+| **Code broken** | Wrong behavior, test failing, unexpected output | debugging skill |
+
+## Process
+
+1. **Identify stuck-type** - What symptom matches above?
+2. **Load that technique** - Read the specific reference file
+3. **Apply technique** - Follow its process
+4. **Document attempt** - What worked/failed?
+5. **If still stuck** - Try different technique or combine
+
+## Combining Techniques
+
+Some problems need multiple techniques:
+
+- **Simplification + Meta-pattern** - Find pattern → simplify all instances
+- **Collision + Inversion** - Force metaphor → invert assumptions
+- **Scale + Simplification** - Test extremes → reveal what to eliminate
+- **Meta-pattern + Scale** - Universal pattern → test at extremes
+
+## When Nothing Works
+
+If no technique helps:
+1. **Reframe problem** - Are you solving the right problem?
+2. **Get fresh perspective** - Explain to someone else
+3. **Take break** - Distance often reveals solution
+4. **Simplify scope** - Solve smaller version first
+5. **Question constraints** - Are they real or assumed?
+
+## Remember
+
+- Match symptom to technique
+- One technique at a time
+- Combine if first doesn't work
+- Document what you tried
+- Not stuck forever, just temporarily