opencode-skills-collection 4.0.53 → 4.0.54

package/bundled-skills/kaizen/SKILL.md

@@ -8,11 +8,9 @@ date_added: "2026-02-27"
 
 # Kaizen: Continuous Improvement
 
-## Overview
+## Detailed Guide
 
-Small improvements, continuously. Error-proof by design. Follow what works. Build only what's needed.
-
-**Core principle:** Many small improvements beat one big change. Prevent errors at design time, not with fixes.
+Read [the detailed guide](references/detailed-guide.md) before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
 
 ## When to Use
 **Always applied for:**
@@ -24,713 +22,6 @@ Small improvements, continuously. Error-proof by design. Follow what works. Buil
 
 **Philosophy:** Quality through incremental progress and prevention, not perfection through massive effort.
 
-## The Four Pillars
-
-### 1. Continuous Improvement (Kaizen)
-
-Small, frequent improvements compound into major gains.
-
-#### Principles
-
-**Incremental over revolutionary:**
-
-- Make smallest viable change that improves quality
-- One improvement at a time
-- Verify each change before next
-- Build momentum through small wins
-
-**Always leave code better:**
-
-- Fix small issues as you encounter them
-- Refactor while you work (within scope)
-- Update outdated comments
-- Remove dead code when you see it
-
-**Iterative refinement:**
-
-- First version: make it work
-- Second pass: make it clear
-- Third pass: make it efficient
-- Don't try all three at once
-
-<Good>
-```typescript
-// Iteration 1: Make it work
-const calculateTotal = (items: Item[]) => {
-  let total = 0;
-  for (let i = 0; i < items.length; i++) {
-    total += items[i].price * items[i].quantity;
-  }
-  return total;
-};
-
-// Iteration 2: Make it clear (refactor)
-const calculateTotal = (items: Item[]): number => {
-return items.reduce((total, item) => {
-return total + (item.price \* item.quantity);
-}, 0);
-};
-
-// Iteration 3: Make it robust (add validation)
-const calculateTotal = (items: Item[]): number => {
-if (!items?.length) return 0;
-
-return items.reduce((total, item) => {
-if (item.price < 0 || item.quantity < 0) {
-throw new Error('Price and quantity must be non-negative');
-}
-return total + (item.price \* item.quantity);
-}, 0);
-};
-
-````
-Each step is complete, tested, and working
-</Good>
-
-<Bad>
-```typescript
-// Trying to do everything at once
-const calculateTotal = (items: Item[]): number => {
-  // Validate, optimize, add features, handle edge cases all together
-  if (!items?.length) return 0;
-  const validItems = items.filter(item => {
-    if (item.price < 0) throw new Error('Negative price');
-    if (item.quantity < 0) throw new Error('Negative quantity');
-    return item.quantity > 0; // Also filtering zero quantities
-  });
-  // Plus caching, plus logging, plus currency conversion...
-  return validItems.reduce(...); // Too many concerns at once
-};
-````
-
-Overwhelming, error-prone, hard to verify
-</Bad>
-
-#### In Practice
-
-**When implementing features:**
-
-1. Start with simplest version that works
-2. Add one improvement (error handling, validation, etc.)
-3. Test and verify
-4. Repeat if time permits
-5. Don't try to make it perfect immediately
-
-**When refactoring:**
-
-- Fix one smell at a time
-- Commit after each improvement
-- Keep tests passing throughout
-- Stop when "good enough" (diminishing returns)
-
-**When reviewing code:**
-
-- Suggest incremental improvements (not rewrites)
-- Prioritize: critical → important → nice-to-have
-- Focus on highest-impact changes first
-- Accept "better than before" even if not perfect
-
-### 2. Poka-Yoke (Error Proofing)
-
-Design systems that prevent errors at compile/design time, not runtime.
-
-#### Principles
-
-**Make errors impossible:**
-
-- Type system catches mistakes
-- Compiler enforces contracts
-- Invalid states unrepresentable
-- Errors caught early (left of production)
-
-**Design for safety:**
-
-- Fail fast and loudly
-- Provide helpful error messages
-- Make correct path obvious
-- Make incorrect path difficult
-
-**Defense in layers:**
-
-1. Type system (compile time)
-2. Validation (runtime, early)
-3. Guards (preconditions)
-4. Error boundaries (graceful degradation)
-
-#### Type System Error Proofing
-
-<Good>
-```typescript
-// Error: string status can be any value
-type OrderBad = {
-  status: string; // Can be "pending", "PENDING", "pnding", anything!
-  total: number;
-};
-
-// Good: Only valid states possible
-type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';
-type Order = {
-status: OrderStatus;
-total: number;
-};
-
-// Better: States with associated data
-type Order =
-| { status: 'pending'; createdAt: Date }
-| { status: 'processing'; startedAt: Date; estimatedCompletion: Date }
-| { status: 'shipped'; trackingNumber: string; shippedAt: Date }
-| { status: 'delivered'; deliveredAt: Date; signature: string };
-
-// Now impossible to have shipped without trackingNumber
-
-````
-Type system prevents entire classes of errors
-</Good>
-
-<Good>
-```typescript
-// Make invalid states unrepresentable
-type NonEmptyArray<T> = [T, ...T[]];
-
-const firstItem = <T>(items: NonEmptyArray<T>): T => {
-  return items[0]; // Always safe, never undefined!
-};
-
-// Caller must prove array is non-empty
-const items: number[] = [1, 2, 3];
-if (items.length > 0) {
-  firstItem(items as NonEmptyArray<number>); // Safe
-}
-````
-
-Function signature guarantees safety
-</Good>
-
-#### Validation Error Proofing
-
-<Good>
-```typescript
-// Error: Validation after use
-const processPayment = (amount: number) => {
-  const fee = amount * 0.03; // Used before validation!
-  if (amount <= 0) throw new Error('Invalid amount');
-  // ...
-};
-
-// Good: Validate immediately
-const processPayment = (amount: number) => {
-if (amount <= 0) {
-throw new Error('Payment amount must be positive');
-}
-if (amount > 10000) {
-throw new Error('Payment exceeds maximum allowed');
-}
-
-const fee = amount \* 0.03;
-// ... now safe to use
-};
-
-// Better: Validation at boundary with branded type
-type PositiveNumber = number & { readonly \_\_brand: 'PositiveNumber' };
-
-const validatePositive = (n: number): PositiveNumber => {
-if (n <= 0) throw new Error('Must be positive');
-return n as PositiveNumber;
-};
-
-const processPayment = (amount: PositiveNumber) => {
-// amount is guaranteed positive, no need to check
-const fee = amount \* 0.03;
-};
-
-// Validate at system boundary
-const handlePaymentRequest = (req: Request) => {
-const amount = validatePositive(req.body.amount); // Validate once
-processPayment(amount); // Use everywhere safely
-};
-
-````
-Validate once at boundary, safe everywhere else
-</Good>
-
-#### Guards and Preconditions
-
-<Good>
-```typescript
-// Early returns prevent deeply nested code
-const processUser = (user: User | null) => {
-  if (!user) {
-    logger.error('User not found');
-    return;
-  }
-
-  if (!user.email) {
-    logger.error('User email missing');
-    return;
-  }
-
-  if (!user.isActive) {
-    logger.info('User inactive, skipping');
-    return;
-  }
-
-  // Main logic here, guaranteed user is valid and active
-  sendEmail(user.email, 'Welcome!');
-};
-````
-
-Guards make assumptions explicit and enforced
-</Good>
-
-#### Configuration Error Proofing
-
-<Good>
-```typescript
-// Error: Optional config with unsafe defaults
-type ConfigBad = {
-  apiKey?: string;
-  timeout?: number;
-};
-
-const client = new APIClient({ timeout: 5000 }); // apiKey missing!
-
-// Good: Required config, fails early
-type Config = {
-apiKey: string;
-timeout: number;
-};
-
-const loadConfig = (): Config => {
-const apiKey = process.env.API_KEY;
-if (!apiKey) {
-throw new Error('API_KEY environment variable required');
-}
-
-return {
-apiKey,
-timeout: 5000,
-};
-};
-
-// App fails at startup if config invalid, not during request
-const config = loadConfig();
-const client = new APIClient(config);
-
-````
-Fail at startup, not in production
-</Good>
-
-#### In Practice
-
-**When designing APIs:**
-- Use types to constrain inputs
-- Make invalid states unrepresentable
-- Return Result<T, E> instead of throwing
-- Document preconditions in types
-
-**When handling errors:**
-- Validate at system boundaries
-
-- Use guards for preconditions
-- Fail fast with clear messages
-- Log context for debugging
-
-**When configuring:**
-- Required over optional with defaults
-- Validate all config at startup
-- Fail deployment if config invalid
-- Don't allow partial configurations
-
-### 3. Standardized Work
-Follow established patterns. Document what works. Make good practices easy to follow.
-
-#### Principles
-
-**Consistency over cleverness:**
-- Follow existing codebase patterns
-- Don't reinvent solved problems
-- New pattern only if significantly better
-- Team agreement on new patterns
-
-**Documentation lives with code:**
-- README for setup and architecture
-- CLAUDE.md for AI coding conventions
-- Comments for "why", not "what"
-- Examples for complex patterns
-
-**Automate standards:**
-- Linters enforce style
-- Type checks enforce contracts
-- Tests verify behavior
-- CI/CD enforces quality gates
-
-#### Following Patterns
-
-<Good>
-```typescript
-// Existing codebase pattern for API clients
-class UserAPIClient {
-  async getUser(id: string): Promise<User> {
-    return this.fetch(`/users/${id}`);
-  }
-}
-
-// New code follows the same pattern
-class OrderAPIClient {
-  async getOrder(id: string): Promise<Order> {
-    return this.fetch(`/orders/${id}`);
-  }
-}
-````
-
-Consistency makes codebase predictable
-</Good>
-
-<Bad>
-```typescript
-// Existing pattern uses classes
-class UserAPIClient { /* ... */ }
-
-// New code introduces different pattern without discussion
-const getOrder = async (id: string): Promise<Order> => {
-// Breaking consistency "because I prefer functions"
-};
-
-````
-Inconsistency creates confusion
-</Bad>
-
-#### Error Handling Patterns
-
-<Good>
-```typescript
-// Project standard: Result type for recoverable errors
-type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
-
-// All services follow this pattern
-const fetchUser = async (id: string): Promise<Result<User, Error>> => {
-  try {
-    const user = await db.users.findById(id);
-    if (!user) {
-      return { ok: false, error: new Error('User not found') };
-    }
-    return { ok: true, value: user };
-  } catch (err) {
-    return { ok: false, error: err as Error };
-  }
-};
-
-// Callers use consistent pattern
-const result = await fetchUser('123');
-if (!result.ok) {
-  logger.error('Failed to fetch user', result.error);
-  return;
-}
-const user = result.value; // Type-safe!
-````
-
-Standard pattern across codebase
-</Good>
-
-#### Documentation Standards
-
-<Good>
-```typescript
-/**
- * Retries an async operation with exponential backoff.
- *
- * Why: Network requests fail temporarily; retrying improves reliability
- * When to use: External API calls, database operations
- * When not to use: User input validation, internal function calls
- *
- * @example
- * const result = await retry(
- *   () => fetch('https://api.example.com/data'),
- *   { maxAttempts: 3, baseDelay: 1000 }
- * );
- */
-const retry = async <T>(
-  operation: () => Promise<T>,
-  options: RetryOptions
-): Promise<T> => {
-  // Implementation...
-};
-```
-Documents why, when, and how
-</Good>
-
-#### In Practice
-
-**Before adding new patterns:**
-
-- Search codebase for similar problems solved
-- Check CLAUDE.md for project conventions
-- Discuss with team if breaking from pattern
-- Update docs when introducing new pattern
-
-**When writing code:**
-
-- Match existing file structure
-- Use same naming conventions
-- Follow same error handling approach
-- Import from same locations
-
-**When reviewing:**
-
-- Check consistency with existing code
-- Point to examples in codebase
-- Suggest aligning with standards
-- Update CLAUDE.md if new standard emerges
-
-### 4. Just-In-Time (JIT)
-
-Build what's needed now. No more, no less. Avoid premature optimization and over-engineering.
-
-#### Principles
-
-**YAGNI (You Aren't Gonna Need It):**
-
-- Implement only current requirements
-- No "just in case" features
-- No "we might need this later" code
-- Delete speculation
-
-**Simplest thing that works:**
-
-- Start with straightforward solution
-- Add complexity only when needed
-- Refactor when requirements change
-- Don't anticipate future needs
-
-**Optimize when measured:**
-
-- No premature optimization
-- Profile before optimizing
-- Measure impact of changes
-- Accept "good enough" performance
-
-#### YAGNI in Action
-
-<Good>
-```typescript
-// Current requirement: Log errors to console
-const logError = (error: Error) => {
-  console.error(error.message);
-};
-```
-Simple, meets current need
-</Good>
-
-<Bad>
-```typescript
-// Over-engineered for "future needs"
-interface LogTransport {
-  write(level: LogLevel, message: string, meta?: LogMetadata): Promise<void>;
-}
-
-class ConsoleTransport implements LogTransport { /_... _/ }
-class FileTransport implements LogTransport { /_ ... _/ }
-class RemoteTransport implements LogTransport { /_ ..._/ }
-
-class Logger {
-private transports: LogTransport[] = [];
-private queue: LogEntry[] = [];
-private rateLimiter: RateLimiter;
-private formatter: LogFormatter;
-
-// 200 lines of code for "maybe we'll need it"
-}
-
-const logError = (error: Error) => {
-Logger.getInstance().log('error', error.message);
-};
-
-````
-Building for imaginary future requirements
-</Bad>
-
-**When to add complexity:**
-- Current requirement demands it
-- Pain points identified through use
-- Measured performance issues
-- Multiple use cases emerged
-
-<Good>
-```typescript
-// Start simple
-const formatCurrency = (amount: number): string => {
-  return `$${amount.toFixed(2)}`;
-};
-
-// Requirement evolves: support multiple currencies
-const formatCurrency = (amount: number, currency: string): string => {
-  const symbols = { USD: '$', EUR: '€', GBP: '£' };
-  return `${symbols[currency]}${amount.toFixed(2)}`;
-};
-
-// Requirement evolves: support localization
-const formatCurrency = (amount: number, locale: string): string => {
-  return new Intl.NumberFormat(locale, {\n    style: 'currency',
-    currency: locale === 'en-US' ? 'USD' : 'EUR',
-  }).format(amount);
-};
-````
-
-Complexity added only when needed
-</Good>
-
-#### Premature Abstraction
-
-<Bad>
-```typescript
-// One use case, but building generic framework
-abstract class BaseCRUDService<T> {
-  abstract getAll(): Promise<T[]>;
-  abstract getById(id: string): Promise<T>;
-  abstract create(data: Partial<T>): Promise<T>;
-  abstract update(id: string, data: Partial<T>): Promise<T>;
-  abstract delete(id: string): Promise<void>;
-}
-
-class GenericRepository<T> { /_300 lines _/ }
-class QueryBuilder<T> { /_ 200 lines_/ }
-// ... building entire ORM for single table
-
-````
-Massive abstraction for uncertain future
-</Bad>
-
-<Good>
-```typescript
-// Simple functions for current needs
-const getUsers = async (): Promise<User[]> => {
-  return db.query('SELECT * FROM users');
-};
-
-const getUserById = async (id: string): Promise<User | null> => {
-  return db.query('SELECT * FROM users WHERE id = $1', [id]);
-};
-
-// When pattern emerges across multiple entities, then abstract
-````
-
-Abstract only when pattern proven across 3+ cases
-</Good>
-
-#### Performance Optimization
-
-<Good>
-```typescript
-// Current: Simple approach
-const filterActiveUsers = (users: User[]): User[] => {
-  return users.filter(user => user.isActive);
-};
-
-// Benchmark shows: 50ms for 1000 users (acceptable)
-// ✓ Ship it, no optimization needed
-
-// Later: After profiling shows this is bottleneck
-// Then optimize with indexed lookup or caching
-
-````
-Optimize based on measurement, not assumptions
-</Good>
-
-<Bad>
-```typescript
-// Premature optimization
-const filterActiveUsers = (users: User[]): User[] => {
-  // "This might be slow, so let's cache and index"
-  const cache = new WeakMap();
-  const indexed = buildBTreeIndex(users, 'isActive');
-  // 100 lines of optimization code
-  // Adds complexity, harder to maintain
-  // No evidence it was needed
-};\
-````
-
-Complex solution for unmeasured problem
-</Bad>
-
-#### In Practice
-
-**When implementing:**
-
-- Solve the immediate problem
-- Use straightforward approach
-- Resist "what if" thinking
-- Delete speculative code
-
-**When optimizing:**
-
-- Profile first, optimize second
-- Measure before and after
-- Document why optimization needed
-- Keep simple version in tests
-
-**When abstracting:**
-
-- Wait for 3+ similar cases (Rule of Three)
-- Make abstraction as simple as possible
-- Prefer duplication over wrong abstraction
-- Refactor when pattern clear
-
-## Integration with Commands
-
-The Kaizen skill guides how you work. The commands provide structured analysis:
-
-- **`/why`**: Root cause analysis (5 Whys)
-- **`/cause-and-effect`**: Multi-factor analysis (Fishbone)
-- **`/plan-do-check-act`**: Iterative improvement cycles
-- **`/analyse-problem`**: Comprehensive documentation (A3)
-- **`/analyse`**: Smart method selection (Gemba/VSM/Muda)
-
-Use commands for structured problem-solving. Apply skill for day-to-day development.
-
-## Red Flags
-
-**Violating Continuous Improvement:**
-
-- "I'll refactor it later" (never happens)
-- Leaving code worse than you found it
-- Big bang rewrites instead of incremental
-
-**Violating Poka-Yoke:**
-
-- "Users should just be careful"
-- Validation after use instead of before
-- Optional config with no validation
-
-**Violating Standardized Work:**
-
-- "I prefer to do it my way"
-- Not checking existing patterns
-- Ignoring project conventions
-
-**Violating Just-In-Time:**
-
-- "We might need this someday"
-- Building frameworks before using them
-- Optimizing without measuring
-
-## Remember
-
-**Kaizen is about:**
-
-- Small improvements continuously
-- Preventing errors by design
-- Following proven patterns
-- Building only what's needed
-
-**Not about:**
-
-- Perfection on first try
-- Massive refactoring projects
-- Clever abstractions
-- Premature optimization
-
-**Mindset:** Good enough today, better tomorrow. Repeat.
-
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.