Kaizen: Continuous Improvement

1---
2name: kaizen
3description: Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements.
4---
5 
6# Kaizen: Continuous Improvement
7 
8## Overview
9 
10Small improvements, continuously. Error-proof by design. Follow what works. Build only what's needed.
11 
12**Core principle:** Many small improvements beat one big change. Prevent errors at design time, not with fixes.
13 
14## When to Use
15 
16**Always applied for:**
17 
18- Code implementation and refactoring
19- Architecture and design decisions
20- Process and workflow improvements
21- Error handling and validation
22 
23**Philosophy:** Quality through incremental progress and prevention, not perfection through massive effort.
24 
25## The Four Pillars
26 
27### 1. Continuous Improvement (Kaizen)
28 
29Small, frequent improvements compound into major gains.
30 
31#### Principles
32 
33**Incremental over revolutionary:**
34 
35- Make smallest viable change that improves quality
36- One improvement at a time
37- Verify each change before next
38- Build momentum through small wins
39 
40**Always leave code better:**
41 
42- Fix small issues as you encounter them
43- Refactor while you work (within scope)
44- Update outdated comments
45- Remove dead code when you see it
46 
47**Iterative refinement:**
48 
49- First version: make it work
50- Second pass: make it clear
51- Third pass: make it efficient
52- Don't try all three at once
53 
54<Good>
55```typescript
56// Iteration 1: Make it work
57const calculateTotal = (items: Item[]) => {
58  let total = 0;
59  for (let i = 0; i < items.length; i++) {
60    total += items[i].price * items[i].quantity;
61  }
62  return total;
63};
64 
65// Iteration 2: Make it clear (refactor)
66const calculateTotal = (items: Item[]): number => {
67return items.reduce((total, item) => {
68return total + (item.price \* item.quantity);
69}, 0);
70};
71 
72// Iteration 3: Make it robust (add validation)
73const calculateTotal = (items: Item[]): number => {
74if (!items?.length) return 0;
75 
76return items.reduce((total, item) => {
77if (item.price < 0 || item.quantity < 0) {
78throw new Error('Price and quantity must be non-negative');
79}
80return total + (item.price \* item.quantity);
81}, 0);
82};
83 
84````
85Each step is complete, tested, and working
86</Good>
87 
88<Bad>
89```typescript
90// Trying to do everything at once
91const calculateTotal = (items: Item[]): number => {
92  // Validate, optimize, add features, handle edge cases all together
93  if (!items?.length) return 0;
94  const validItems = items.filter(item => {
95    if (item.price < 0) throw new Error('Negative price');
96    if (item.quantity < 0) throw new Error('Negative quantity');
97    return item.quantity > 0; // Also filtering zero quantities
98  });
99  // Plus caching, plus logging, plus currency conversion...
100  return validItems.reduce(...); // Too many concerns at once
101};
102````
103 
104Overwhelming, error-prone, hard to verify
105</Bad>
106 
107#### In Practice
108 
109**When implementing features:**
110 
1111. Start with simplest version that works
1122. Add one improvement (error handling, validation, etc.)
1133. Test and verify
1144. Repeat if time permits
1155. Don't try to make it perfect immediately
116 
117**When refactoring:**
118 
119- Fix one smell at a time
120- Commit after each improvement
121- Keep tests passing throughout
122- Stop when "good enough" (diminishing returns)
123 
124**When reviewing code:**
125 
126- Suggest incremental improvements (not rewrites)
127- Prioritize: critical → important → nice-to-have
128- Focus on highest-impact changes first
129- Accept "better than before" even if not perfect
130 
131### 2. Poka-Yoke (Error Proofing)
132 
133Design systems that prevent errors at compile/design time, not runtime.
134 
135#### Principles
136 
137**Make errors impossible:**
138 
139- Type system catches mistakes
140- Compiler enforces contracts
141- Invalid states unrepresentable
142- Errors caught early (left of production)
143 
144**Design for safety:**
145 
146- Fail fast and loudly
147- Provide helpful error messages
148- Make correct path obvious
149- Make incorrect path difficult
150 
151**Defense in layers:**
152 
1531. Type system (compile time)
1542. Validation (runtime, early)
1553. Guards (preconditions)
1564. Error boundaries (graceful degradation)
157 
158#### Type System Error Proofing
159 
160<Good>
161```typescript
162// Error: string status can be any value
163type OrderBad = {
164  status: string; // Can be "pending", "PENDING", "pnding", anything!
165  total: number;
166};
167 
168// Good: Only valid states possible
169type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';
170type Order = {
171status: OrderStatus;
172total: number;
173};
174 
175// Better: States with associated data
176type Order =
177| { status: 'pending'; createdAt: Date }
178| { status: 'processing'; startedAt: Date; estimatedCompletion: Date }
179| { status: 'shipped'; trackingNumber: string; shippedAt: Date }
180| { status: 'delivered'; deliveredAt: Date; signature: string };
181 
182// Now impossible to have shipped without trackingNumber
183 
184````
185Type system prevents entire classes of errors
186</Good>
187 
188<Good>
189```typescript
190// Make invalid states unrepresentable
191type NonEmptyArray<T> = [T, ...T[]];
192 
193const firstItem = <T>(items: NonEmptyArray<T>): T => {
194  return items[0]; // Always safe, never undefined!
195};
196 
197// Caller must prove array is non-empty
198const items: number[] = [1, 2, 3];
199if (items.length > 0) {
200  firstItem(items as NonEmptyArray<number>); // Safe
201}
202````
203 
204Function signature guarantees safety
205</Good>
206 
207#### Validation Error Proofing
208 
209<Good>
210```typescript
211// Error: Validation after use
212const processPayment = (amount: number) => {
213  const fee = amount * 0.03; // Used before validation!
214  if (amount <= 0) throw new Error('Invalid amount');
215  // ...
216};
217 
218// Good: Validate immediately
219const processPayment = (amount: number) => {
220if (amount <= 0) {
221throw new Error('Payment amount must be positive');
222}
223if (amount > 10000) {
224throw new Error('Payment exceeds maximum allowed');
225}
226 
227const fee = amount \* 0.03;
228// ... now safe to use
229};
230 
231// Better: Validation at boundary with branded type
232type PositiveNumber = number & { readonly \_\_brand: 'PositiveNumber' };
233 
234const validatePositive = (n: number): PositiveNumber => {
235if (n <= 0) throw new Error('Must be positive');
236return n as PositiveNumber;
237};
238 
239const processPayment = (amount: PositiveNumber) => {
240// amount is guaranteed positive, no need to check
241const fee = amount \* 0.03;
242};
243 
244// Validate at system boundary
245const handlePaymentRequest = (req: Request) => {
246const amount = validatePositive(req.body.amount); // Validate once
247processPayment(amount); // Use everywhere safely
248};
249 
250````
251Validate once at boundary, safe everywhere else
252</Good>
253 
254#### Guards and Preconditions
255 
256<Good>
257```typescript
258// Early returns prevent deeply nested code
259const processUser = (user: User | null) => {
260  if (!user) {
261    logger.error('User not found');
262    return;
263  }
264 
265  if (!user.email) {
266    logger.error('User email missing');
267    return;
268  }
269 
270  if (!user.isActive) {
271    logger.info('User inactive, skipping');
272    return;
273  }
274 
275  // Main logic here, guaranteed user is valid and active
276  sendEmail(user.email, 'Welcome!');
277};
278````
279 
280Guards make assumptions explicit and enforced
281</Good>
282 
283#### Configuration Error Proofing
284 
285<Good>
286```typescript
287// Error: Optional config with unsafe defaults
288type ConfigBad = {
289  apiKey?: string;
290  timeout?: number;
291};
292 
293const client = new APIClient({ timeout: 5000 }); // apiKey missing!
294 
295// Good: Required config, fails early
296type Config = {
297apiKey: string;
298timeout: number;
299};
300 
301const loadConfig = (): Config => {
302const apiKey = process.env.API_KEY;
303if (!apiKey) {
304throw new Error('API_KEY environment variable required');
305}
306 
307return {
308apiKey,
309timeout: 5000,
310};
311};
312 
313// App fails at startup if config invalid, not during request
314const config = loadConfig();
315const client = new APIClient(config);
316 
317````
318Fail at startup, not in production
319</Good>
320 
321#### In Practice
322 
323**When designing APIs:**
324- Use types to constrain inputs
325- Make invalid states unrepresentable
326- Return Result<T, E> instead of throwing
327- Document preconditions in types
328 
329**When handling errors:**
330- Validate at system boundaries
331 
332- Use guards for preconditions
333- Fail fast with clear messages
334- Log context for debugging
335 
336**When configuring:**
337- Required over optional with defaults
338- Validate all config at startup
339- Fail deployment if config invalid
340- Don't allow partial configurations
341 
342### 3. Standardized Work
343Follow established patterns. Document what works. Make good practices easy to follow.
344 
345#### Principles
346 
347**Consistency over cleverness:**
348- Follow existing codebase patterns
349- Don't reinvent solved problems
350- New pattern only if significantly better
351- Team agreement on new patterns
352 
353**Documentation lives with code:**
354- README for setup and architecture
355- CLAUDE.md for AI coding conventions
356- Comments for "why", not "what"
357- Examples for complex patterns
358 
359**Automate standards:**
360- Linters enforce style
361- Type checks enforce contracts
362- Tests verify behavior
363- CI/CD enforces quality gates
364 
365#### Following Patterns
366 
367<Good>
368```typescript
369// Existing codebase pattern for API clients
370class UserAPIClient {
371  async getUser(id: string): Promise<User> {
372    return this.fetch(`/users/${id}`);
373  }
374}
375 
376// New code follows the same pattern
377class OrderAPIClient {
378  async getOrder(id: string): Promise<Order> {
379    return this.fetch(`/orders/${id}`);
380  }
381}
382````
383 
384Consistency makes codebase predictable
385</Good>
386 
387<Bad>
388```typescript
389// Existing pattern uses classes
390class UserAPIClient { /* ... */ }
391 
392// New code introduces different pattern without discussion
393const getOrder = async (id: string): Promise<Order> => {
394// Breaking consistency "because I prefer functions"
395};
396 
397````
398Inconsistency creates confusion
399</Bad>
400 
401#### Error Handling Patterns
402 
403<Good>
404```typescript
405// Project standard: Result type for recoverable errors
406type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
407 
408// All services follow this pattern
409const fetchUser = async (id: string): Promise<Result<User, Error>> => {
410  try {
411    const user = await db.users.findById(id);
412    if (!user) {
413      return { ok: false, error: new Error('User not found') };
414    }
415    return { ok: true, value: user };
416  } catch (err) {
417    return { ok: false, error: err as Error };
418  }
419};
420 
421// Callers use consistent pattern
422const result = await fetchUser('123');
423if (!result.ok) {
424  logger.error('Failed to fetch user', result.error);
425  return;
426}
427const user = result.value; // Type-safe!
428````
429 
430Standard pattern across codebase
431</Good>
432 
433#### Documentation Standards
434 
435<Good>
436```typescript
437/**
438 * Retries an async operation with exponential backoff.
439 *
440 * Why: Network requests fail temporarily; retrying improves reliability
441 * When to use: External API calls, database operations
442 * When not to use: User input validation, internal function calls
443 *
444 * @example
445 * const result = await retry(
446 *   () => fetch('https://api.example.com/data'),
447 *   { maxAttempts: 3, baseDelay: 1000 }
448 * );
449 */
450const retry = async <T>(
451  operation: () => Promise<T>,
452  options: RetryOptions
453): Promise<T> => {
454  // Implementation...
455};
456```
457Documents why, when, and how
458</Good>
459 
460#### In Practice
461 
462**Before adding new patterns:**
463 
464- Search codebase for similar problems solved
465- Check CLAUDE.md for project conventions
466- Discuss with team if breaking from pattern
467- Update docs when introducing new pattern
468 
469**When writing code:**
470 
471- Match existing file structure
472- Use same naming conventions
473- Follow same error handling approach
474- Import from same locations
475 
476**When reviewing:**
477 
478- Check consistency with existing code
479- Point to examples in codebase
480- Suggest aligning with standards
481- Update CLAUDE.md if new standard emerges
482 
483### 4. Just-In-Time (JIT)
484 
485Build what's needed now. No more, no less. Avoid premature optimization and over-engineering.
486 
487#### Principles
488 
489**YAGNI (You Aren't Gonna Need It):**
490 
491- Implement only current requirements
492- No "just in case" features
493- No "we might need this later" code
494- Delete speculation
495 
496**Simplest thing that works:**
497 
498- Start with straightforward solution
499- Add complexity only when needed
500- Refactor when requirements change
501- Don't anticipate future needs
502 
503**Optimize when measured:**
504 
505- No premature optimization
506- Profile before optimizing
507- Measure impact of changes
508- Accept "good enough" performance
509 
510#### YAGNI in Action
511 
512<Good>
513```typescript
514// Current requirement: Log errors to console
515const logError = (error: Error) => {
516  console.error(error.message);
517};
518```
519Simple, meets current need
520</Good>
521 
522<Bad>
523```typescript
524// Over-engineered for "future needs"
525interface LogTransport {
526  write(level: LogLevel, message: string, meta?: LogMetadata): Promise<void>;
527}
528 
529class ConsoleTransport implements LogTransport { /_... _/ }
530class FileTransport implements LogTransport { /_ ... _/ }
531class RemoteTransport implements LogTransport { /_ ..._/ }
532 
533class Logger {
534private transports: LogTransport[] = [];
535private queue: LogEntry[] = [];
536private rateLimiter: RateLimiter;
537private formatter: LogFormatter;
538 
539// 200 lines of code for "maybe we'll need it"
540}
541 
542const logError = (error: Error) => {
543Logger.getInstance().log('error', error.message);
544};
545 
546````
547Building for imaginary future requirements
548</Bad>
549 
550**When to add complexity:**
551- Current requirement demands it
552- Pain points identified through use
553- Measured performance issues
554- Multiple use cases emerged
555 
556<Good>
557```typescript
558// Start simple
559const formatCurrency = (amount: number): string => {
560  return `$${amount.toFixed(2)}`;
561};
562 
563// Requirement evolves: support multiple currencies
564const formatCurrency = (amount: number, currency: string): string => {
565  const symbols = { USD: '$', EUR: '€', GBP: '£' };
566  return `${symbols[currency]}${amount.toFixed(2)}`;
567};
568 
569// Requirement evolves: support localization
570const formatCurrency = (amount: number, locale: string): string => {
571  return new Intl.NumberFormat(locale, {\n    style: 'currency',
572    currency: locale === 'en-US' ? 'USD' : 'EUR',
573  }).format(amount);
574};
575````
576 
577Complexity added only when needed
578</Good>
579 
580#### Premature Abstraction
581 
582<Bad>
583```typescript
584// One use case, but building generic framework
585abstract class BaseCRUDService<T> {
586  abstract getAll(): Promise<T[]>;
587  abstract getById(id: string): Promise<T>;
588  abstract create(data: Partial<T>): Promise<T>;
589  abstract update(id: string, data: Partial<T>): Promise<T>;
590  abstract delete(id: string): Promise<void>;
591}
592 
593class GenericRepository<T> { /_300 lines _/ }
594class QueryBuilder<T> { /_ 200 lines_/ }
595// ... building entire ORM for single table
596 
597````
598Massive abstraction for uncertain future
599</Bad>
600 
601<Good>
602```typescript
603// Simple functions for current needs
604const getUsers = async (): Promise<User[]> => {
605  return db.query('SELECT * FROM users');
606};
607 
608const getUserById = async (id: string): Promise<User | null> => {
609  return db.query('SELECT * FROM users WHERE id = $1', [id]);
610};
611 
612// When pattern emerges across multiple entities, then abstract
613````
614 
615Abstract only when pattern proven across 3+ cases
616</Good>
617 
618#### Performance Optimization
619 
620<Good>
621```typescript
622// Current: Simple approach
623const filterActiveUsers = (users: User[]): User[] => {
624  return users.filter(user => user.isActive);
625};
626 
627// Benchmark shows: 50ms for 1000 users (acceptable)
628// ✓ Ship it, no optimization needed
629 
630// Later: After profiling shows this is bottleneck
631// Then optimize with indexed lookup or caching
632 
633````
634Optimize based on measurement, not assumptions
635</Good>
636 
637<Bad>
638```typescript
639// Premature optimization
640const filterActiveUsers = (users: User[]): User[] => {
641  // "This might be slow, so let's cache and index"
642  const cache = new WeakMap();
643  const indexed = buildBTreeIndex(users, 'isActive');
644  // 100 lines of optimization code
645  // Adds complexity, harder to maintain
646  // No evidence it was needed
647};\
648````
649 
650Complex solution for unmeasured problem
651</Bad>
652 
653#### In Practice
654 
655**When implementing:**
656 
657- Solve the immediate problem
658- Use straightforward approach
659- Resist "what if" thinking
660- Delete speculative code
661 
662**When optimizing:**
663 
664- Profile first, optimize second
665- Measure before and after
666- Document why optimization needed
667- Keep simple version in tests
668 
669**When abstracting:**
670 
671- Wait for 3+ similar cases (Rule of Three)
672- Make abstraction as simple as possible
673- Prefer duplication over wrong abstraction
674- Refactor when pattern clear
675 
676## Integration with Commands
677 
678The Kaizen skill guides how you work. The commands provide structured analysis:
679 
680- **`/why`**: Root cause analysis (5 Whys)
681- **`/cause-and-effect`**: Multi-factor analysis (Fishbone)
682- **`/plan-do-check-act`**: Iterative improvement cycles
683- **`/analyse-problem`**: Comprehensive documentation (A3)
684- **`/analyse`**: Smart method selection (Gemba/VSM/Muda)
685 
686Use commands for structured problem-solving. Apply skill for day-to-day development.
687 
688## Red Flags
689 
690**Violating Continuous Improvement:**
691 
692- "I'll refactor it later" (never happens)
693- Leaving code worse than you found it
694- Big bang rewrites instead of incremental
695 
696**Violating Poka-Yoke:**
697 
698- "Users should just be careful"
699- Validation after use instead of before
700- Optional config with no validation
701 
702**Violating Standardized Work:**
703 
704- "I prefer to do it my way"
705- Not checking existing patterns
706- Ignoring project conventions
707 
708**Violating Just-In-Time:**
709 
710- "We might need this someday"
711- Building frameworks before using them
712- Optimizing without measuring
713 
714## Remember
715 
716**Kaizen is about:**
717 
718- Small improvements continuously
719- Preventing errors by design
720- Following proven patterns
721- Building only what's needed
722 
723**Not about:**
724 
725- Perfection on first try
726- Massive refactoring projects
727- Clever abstractions
728- Premature optimization
729 
730**Mindset:** Good enough today, better tomorrow. Repeat.
731