Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements.
Add this skill
npx mdskills install sickn33/kaizenComprehensive philosophy guide with clear TypeScript examples demonstrating iterative improvement patterns
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.
Always applied for:
Philosophy: Quality through incremental progress and prevention, not perfection through massive effort.
Small, frequent improvements compound into major gains.
Incremental over revolutionary:
Always leave code better:
Iterative refinement:
// Iteration 1: Make it work
const calculateTotal = (items: Item[]) => {
let total = 0;
for (let i = 0; i {
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
```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; // 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
When implementing features:
When refactoring:
When reviewing code:
Design systems that prevent errors at compile/design time, not runtime.
Make errors impossible:
Design for safety:
Defense in layers:
// 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
// Make invalid states unrepresentable
type NonEmptyArray = [T, ...T[]];
const firstItem = (items: NonEmptyArray): 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); // Safe
}
Function signature guarantees safety
// Error: Validation after use
const processPayment = (amount: number) => {
const fee = amount * 0.03; // Used before validation!
if (amount {
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 {
// 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
// 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
// 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
When designing APIs:
When handling errors:
Validate at system boundaries
Use guards for preconditions
Fail fast with clear messages
Log context for debugging
When configuring:
Follow established patterns. Document what works. Make good practices easy to follow.
Consistency over cleverness:
Documentation lives with code:
Automate standards:
// Existing codebase pattern for API clients
class UserAPIClient {
async getUser(id: string): Promise {
return this.fetch(`/users/${id}`);
}
}
// New code follows the same pattern
class OrderAPIClient {
async getOrder(id: string): Promise {
return this.fetch(`/orders/${id}`);
}
}
Consistency makes codebase predictable
// Existing pattern uses classes
class UserAPIClient { /* ... */ }
// New code introduces different pattern without discussion
const getOrder = async (id: string): Promise => {
// Breaking consistency "because I prefer functions"
};
Inconsistency creates confusion
// Project standard: Result type for recoverable errors
type Result = { ok: true; value: T } | { ok: false; error: E };
// All services follow this pattern
const fetchUser = async (id: string): Promise> => {
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
/**
* 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 (
operation: () => Promise,
options: RetryOptions
): Promise => {
// Implementation...
};
Documents why, when, and how
Before adding new patterns:
When writing code:
When reviewing:
Build what's needed now. No more, no less. Avoid premature optimization and over-engineering.
YAGNI (You Aren't Gonna Need It):
Simplest thing that works:
Optimize when measured:
// Current requirement: Log errors to console
const logError = (error: Error) => {
console.error(error.message);
};
Simple, meets current need
// Over-engineered for "future needs"
interface LogTransport {
write(level: LogLevel, message: string, meta?: LogMetadata): Promise;
}
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
When to add complexity:
// 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
// One use case, but building generic framework
abstract class BaseCRUDService {
abstract getAll(): Promise;
abstract getById(id: string): Promise;
abstract create(data: Partial): Promise;
abstract update(id: string, data: Partial): Promise;
abstract delete(id: string): Promise;
}
class GenericRepository { /_300 lines _/ }
class QueryBuilder { /_ 200 lines_/ }
// ... building entire ORM for single table
Massive abstraction for uncertain future
// Simple functions for current needs
const getUsers = async (): Promise => {
return db.query('SELECT * FROM users');
};
const getUserById = async (id: string): Promise => {
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
// 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
// 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
When implementing:
When optimizing:
When abstracting:
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.
Violating Continuous Improvement:
Violating Poka-Yoke:
Violating Standardized Work:
Violating Just-In-Time:
Kaizen is about:
Not about:
Mindset: Good enough today, better tomorrow. Repeat.
Install via CLI
npx mdskills install sickn33/kaizenKaizen: Continuous Improvement is a free, open-source AI agent skill. Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements.
Install Kaizen: Continuous Improvement with a single command:
npx mdskills install sickn33/kaizenThis downloads the skill files into your project and your AI agent picks them up automatically.
Kaizen: Continuous Improvement works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Codex, Gemini Cli, Amp, Roo Code, Goose, Opencode, Trae, Qodo, Command Code. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.