kaizen — Skillopedia

Kaizen: Continuous Improvement Overview 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. When to Use Always applied for: - Code implementation and refactoring - Architecture and design decisions - Process and workflow improvements - Error handling and validation Philosophy: Quality through incremental progress and prevention, not perfection through massive effort. The Four Pillars 1. Continuous Improvement (Kaizen) Small, frequent imp…

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

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.