📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "agentic-bundle-essentials",
|
||||
"version": "14.2.0",
|
||||
"version": "14.3.1",
|
||||
"description": "Editorial \"Essentials\" bundle for Claude Code from Agentic Awesome Skills.",
|
||||
"author": {
|
||||
"name": "sickn33 and contributors",
|
||||
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "aasb-essentials",
|
||||
"version": "14.2.0",
|
||||
"version": "14.3.1",
|
||||
"description": "Install the \"Essentials\" editorial skill bundle from Agentic Awesome Skills.",
|
||||
"author": {
|
||||
"name": "sickn33 and contributors",
|
||||
@@ -20,7 +20,7 @@
|
||||
"interface": {
|
||||
"displayName": "Essentials",
|
||||
"shortDescription": "Essentials & Core · 5 curated skills",
|
||||
"longDescription": "For everyone. Install these first. Covers Concise Planning, Lint And Validate, and 3 more skills.",
|
||||
"longDescription": "For everyone. Install these first. Covers Concise Planning, Test Driven Development, and 3 more skills.",
|
||||
"developerName": "sickn33 and contributors",
|
||||
"category": "Essentials & Core",
|
||||
"capabilities": [
|
||||
|
||||
@@ -1,737 +0,0 @@
|
||||
---
|
||||
name: kaizen
|
||||
description: "Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements."
|
||||
risk: unknown
|
||||
source: community
|
||||
date_added: "2026-02-27"
|
||||
---
|
||||
|
||||
# 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 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.
|
||||
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||
+378
@@ -0,0 +1,378 @@
|
||||
---
|
||||
name: test-driven-development
|
||||
description: "Use when implementing any feature or bugfix, before writing implementation code"
|
||||
risk: unknown
|
||||
source: community
|
||||
date_added: "2026-02-27"
|
||||
---
|
||||
|
||||
# Test-Driven Development (TDD)
|
||||
|
||||
## Overview
|
||||
|
||||
Write the test first. Watch it fail. Write minimal code to pass.
|
||||
|
||||
**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
|
||||
|
||||
**Violating the letter of the rules is violating the spirit of the rules.**
|
||||
|
||||
## When to Use
|
||||
**Always:**
|
||||
- New features
|
||||
- Bug fixes
|
||||
- Refactoring
|
||||
- Behavior changes
|
||||
|
||||
**Exceptions (ask your human partner):**
|
||||
- Throwaway prototypes
|
||||
- Generated code
|
||||
- Configuration files
|
||||
|
||||
Thinking "skip TDD just this once"? Stop. That's rationalization.
|
||||
|
||||
## The Iron Law
|
||||
|
||||
```
|
||||
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
|
||||
```
|
||||
|
||||
Write code before the test? Delete it. Start over.
|
||||
|
||||
**No exceptions:**
|
||||
- Don't keep it as "reference"
|
||||
- Don't "adapt" it while writing tests
|
||||
- Don't look at it
|
||||
- Delete means delete
|
||||
|
||||
Implement fresh from tests. Period.
|
||||
|
||||
## Red-Green-Refactor
|
||||
|
||||
```dot
|
||||
digraph tdd_cycle {
|
||||
rankdir=LR;
|
||||
red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
|
||||
verify_red [label="Verify fails\ncorrectly", shape=diamond];
|
||||
green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
|
||||
verify_green [label="Verify passes\nAll green", shape=diamond];
|
||||
refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
|
||||
next [label="Next", shape=ellipse];
|
||||
|
||||
red -> verify_red;
|
||||
verify_red -> green [label="yes"];
|
||||
verify_red -> red [label="wrong\nfailure"];
|
||||
green -> verify_green;
|
||||
verify_green -> refactor [label="yes"];
|
||||
verify_green -> green [label="no"];
|
||||
refactor -> verify_green [label="stay\ngreen"];
|
||||
verify_green -> next;
|
||||
next -> red;
|
||||
}
|
||||
```
|
||||
|
||||
### RED - Write Failing Test
|
||||
|
||||
Write one minimal test showing what should happen.
|
||||
|
||||
<Good>
|
||||
```typescript
|
||||
test('retries failed operations 3 times', async () => {
|
||||
let attempts = 0;
|
||||
const operation = () => {
|
||||
attempts++;
|
||||
if (attempts < 3) throw new Error('fail');
|
||||
return 'success';
|
||||
};
|
||||
|
||||
const result = await retryOperation(operation);
|
||||
|
||||
expect(result).toBe('success');
|
||||
expect(attempts).toBe(3);
|
||||
});
|
||||
```
|
||||
Clear name, tests real behavior, one thing
|
||||
</Good>
|
||||
|
||||
<Bad>
|
||||
```typescript
|
||||
test('retry works', async () => {
|
||||
const mock = jest.fn()
|
||||
.mockRejectedValueOnce(new Error())
|
||||
.mockRejectedValueOnce(new Error())
|
||||
.mockResolvedValueOnce('success');
|
||||
await retryOperation(mock);
|
||||
expect(mock).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
```
|
||||
Vague name, tests mock not code
|
||||
</Bad>
|
||||
|
||||
**Requirements:**
|
||||
- One behavior
|
||||
- Clear name
|
||||
- Real code (no mocks unless unavoidable)
|
||||
|
||||
### Verify RED - Watch It Fail
|
||||
|
||||
**MANDATORY. Never skip.**
|
||||
|
||||
```bash
|
||||
npm test path/to/test.test.ts
|
||||
```
|
||||
|
||||
Confirm:
|
||||
- Test fails (not errors)
|
||||
- Failure message is expected
|
||||
- Fails because feature missing (not typos)
|
||||
|
||||
**Test passes?** You're testing existing behavior. Fix test.
|
||||
|
||||
**Test errors?** Fix error, re-run until it fails correctly.
|
||||
|
||||
### GREEN - Minimal Code
|
||||
|
||||
Write simplest code to pass the test.
|
||||
|
||||
<Good>
|
||||
```typescript
|
||||
async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
|
||||
for (let i = 0; i < 3; i++) {
|
||||
try {
|
||||
return await fn();
|
||||
} catch (e) {
|
||||
if (i === 2) throw e;
|
||||
}
|
||||
}
|
||||
throw new Error('unreachable');
|
||||
}
|
||||
```
|
||||
Just enough to pass
|
||||
</Good>
|
||||
|
||||
<Bad>
|
||||
```typescript
|
||||
async function retryOperation<T>(
|
||||
fn: () => Promise<T>,
|
||||
options?: {
|
||||
maxRetries?: number;
|
||||
backoff?: 'linear' | 'exponential';
|
||||
onRetry?: (attempt: number) => void;
|
||||
}
|
||||
): Promise<T> {
|
||||
// YAGNI
|
||||
}
|
||||
```
|
||||
Over-engineered
|
||||
</Bad>
|
||||
|
||||
Don't add features, refactor other code, or "improve" beyond the test.
|
||||
|
||||
### Verify GREEN - Watch It Pass
|
||||
|
||||
**MANDATORY.**
|
||||
|
||||
```bash
|
||||
npm test path/to/test.test.ts
|
||||
```
|
||||
|
||||
Confirm:
|
||||
- Test passes
|
||||
- Other tests still pass
|
||||
- Output pristine (no errors, warnings)
|
||||
|
||||
**Test fails?** Fix code, not test.
|
||||
|
||||
**Other tests fail?** Fix now.
|
||||
|
||||
### REFACTOR - Clean Up
|
||||
|
||||
After green only:
|
||||
- Remove duplication
|
||||
- Improve names
|
||||
- Extract helpers
|
||||
|
||||
Keep tests green. Don't add behavior.
|
||||
|
||||
### Repeat
|
||||
|
||||
Next failing test for next feature.
|
||||
|
||||
## Good Tests
|
||||
|
||||
| Quality | Good | Bad |
|
||||
|---------|------|-----|
|
||||
| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
|
||||
| **Clear** | Name describes behavior | `test('test1')` |
|
||||
| **Shows intent** | Demonstrates desired API | Obscures what code should do |
|
||||
|
||||
## Why Order Matters
|
||||
|
||||
**"I'll write tests after to verify it works"**
|
||||
|
||||
Tests written after code pass immediately. Passing immediately proves nothing:
|
||||
- Might test wrong thing
|
||||
- Might test implementation, not behavior
|
||||
- Might miss edge cases you forgot
|
||||
- You never saw it catch the bug
|
||||
|
||||
Test-first forces you to see the test fail, proving it actually tests something.
|
||||
|
||||
**"I already manually tested all the edge cases"**
|
||||
|
||||
Manual testing is ad-hoc. You think you tested everything but:
|
||||
- No record of what you tested
|
||||
- Can't re-run when code changes
|
||||
- Easy to forget cases under pressure
|
||||
- "It worked when I tried it" ≠ comprehensive
|
||||
|
||||
Automated tests are systematic. They run the same way every time.
|
||||
|
||||
**"Deleting X hours of work is wasteful"**
|
||||
|
||||
Sunk cost fallacy. The time is already gone. Your choice now:
|
||||
- Delete and rewrite with TDD (X more hours, high confidence)
|
||||
- Keep it and add tests after (30 min, low confidence, likely bugs)
|
||||
|
||||
The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
|
||||
|
||||
**"TDD is dogmatic, being pragmatic means adapting"**
|
||||
|
||||
TDD IS pragmatic:
|
||||
- Finds bugs before commit (faster than debugging after)
|
||||
- Prevents regressions (tests catch breaks immediately)
|
||||
- Documents behavior (tests show how to use code)
|
||||
- Enables refactoring (change freely, tests catch breaks)
|
||||
|
||||
"Pragmatic" shortcuts = debugging in production = slower.
|
||||
|
||||
**"Tests after achieve the same goals - it's spirit not ritual"**
|
||||
|
||||
No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
|
||||
|
||||
Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
|
||||
|
||||
Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
|
||||
|
||||
30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
|
||||
|
||||
## Common Rationalizations
|
||||
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
|
||||
| "I'll test after" | Tests passing immediately prove nothing. |
|
||||
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
|
||||
| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
|
||||
| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
|
||||
| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
|
||||
| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
|
||||
| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
|
||||
| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
|
||||
| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
|
||||
| "Existing code has no tests" | You're improving it. Add tests for existing code. |
|
||||
|
||||
## Red Flags - STOP and Start Over
|
||||
|
||||
- Code before test
|
||||
- Test after implementation
|
||||
- Test passes immediately
|
||||
- Can't explain why test failed
|
||||
- Tests added "later"
|
||||
- Rationalizing "just this once"
|
||||
- "I already manually tested it"
|
||||
- "Tests after achieve the same purpose"
|
||||
- "It's about spirit not ritual"
|
||||
- "Keep as reference" or "adapt existing code"
|
||||
- "Already spent X hours, deleting is wasteful"
|
||||
- "TDD is dogmatic, I'm being pragmatic"
|
||||
- "This is different because..."
|
||||
|
||||
**All of these mean: Delete code. Start over with TDD.**
|
||||
|
||||
## Example: Bug Fix
|
||||
|
||||
**Bug:** Empty email accepted
|
||||
|
||||
**RED**
|
||||
```typescript
|
||||
test('rejects empty email', async () => {
|
||||
const result = await submitForm({ email: '' });
|
||||
expect(result.error).toBe('Email required');
|
||||
});
|
||||
```
|
||||
|
||||
**Verify RED**
|
||||
```bash
|
||||
$ npm test
|
||||
FAIL: expected 'Email required', got undefined
|
||||
```
|
||||
|
||||
**GREEN**
|
||||
```typescript
|
||||
function submitForm(data: FormData) {
|
||||
if (!data.email?.trim()) {
|
||||
return { error: 'Email required' };
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**Verify GREEN**
|
||||
```bash
|
||||
$ npm test
|
||||
PASS
|
||||
```
|
||||
|
||||
**REFACTOR**
|
||||
Extract validation for multiple fields if needed.
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before marking work complete:
|
||||
|
||||
- [ ] Every new function/method has a test
|
||||
- [ ] Watched each test fail before implementing
|
||||
- [ ] Each test failed for expected reason (feature missing, not typo)
|
||||
- [ ] Wrote minimal code to pass each test
|
||||
- [ ] All tests pass
|
||||
- [ ] Output pristine (no errors, warnings)
|
||||
- [ ] Tests use real code (mocks only if unavoidable)
|
||||
- [ ] Edge cases and errors covered
|
||||
|
||||
Can't check all boxes? You skipped TDD. Start over.
|
||||
|
||||
## When Stuck
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
|
||||
| Test too complicated | Design too complicated. Simplify interface. |
|
||||
| Must mock everything | Code too coupled. Use dependency injection. |
|
||||
| Test setup huge | Extract helpers. Still complex? Simplify design. |
|
||||
|
||||
## Debugging Integration
|
||||
|
||||
Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
|
||||
|
||||
Never fix bugs without a test.
|
||||
|
||||
## Testing Anti-Patterns
|
||||
|
||||
When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
|
||||
- Testing mock behavior instead of real behavior
|
||||
- Adding test-only methods to production classes
|
||||
- Mocking without understanding dependencies
|
||||
|
||||
## Final Rule
|
||||
|
||||
```
|
||||
Production code → test exists and failed first
|
||||
Otherwise → not TDD
|
||||
```
|
||||
|
||||
No exceptions without your human partner's permission.
|
||||
|
||||
## 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.
|
||||
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||
+299
@@ -0,0 +1,299 @@
|
||||
# Testing Anti-Patterns
|
||||
|
||||
**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
|
||||
|
||||
## Overview
|
||||
|
||||
Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
|
||||
|
||||
**Core principle:** Test what the code does, not what the mocks do.
|
||||
|
||||
**Following strict TDD prevents these anti-patterns.**
|
||||
|
||||
## The Iron Laws
|
||||
|
||||
```
|
||||
1. NEVER test mock behavior
|
||||
2. NEVER add test-only methods to production classes
|
||||
3. NEVER mock without understanding dependencies
|
||||
```
|
||||
|
||||
## Anti-Pattern 1: Testing Mock Behavior
|
||||
|
||||
**The violation:**
|
||||
```typescript
|
||||
// ❌ BAD: Testing that the mock exists
|
||||
test('renders sidebar', () => {
|
||||
render(<Page />);
|
||||
expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
|
||||
});
|
||||
```
|
||||
|
||||
**Why this is wrong:**
|
||||
- You're verifying the mock works, not that the component works
|
||||
- Test passes when mock is present, fails when it's not
|
||||
- Tells you nothing about real behavior
|
||||
|
||||
**your human partner's correction:** "Are we testing the behavior of a mock?"
|
||||
|
||||
**The fix:**
|
||||
```typescript
|
||||
// ✅ GOOD: Test real component or don't mock it
|
||||
test('renders sidebar', () => {
|
||||
render(<Page />); // Don't mock sidebar
|
||||
expect(screen.getByRole('navigation')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
// OR if sidebar must be mocked for isolation:
|
||||
// Don't assert on the mock - test Page's behavior with sidebar present
|
||||
```
|
||||
|
||||
### Gate Function
|
||||
|
||||
```
|
||||
BEFORE asserting on any mock element:
|
||||
Ask: "Am I testing real component behavior or just mock existence?"
|
||||
|
||||
IF testing mock existence:
|
||||
STOP - Delete the assertion or unmock the component
|
||||
|
||||
Test real behavior instead
|
||||
```
|
||||
|
||||
## Anti-Pattern 2: Test-Only Methods in Production
|
||||
|
||||
**The violation:**
|
||||
```typescript
|
||||
// ❌ BAD: destroy() only used in tests
|
||||
class Session {
|
||||
async destroy() { // Looks like production API!
|
||||
await this._workspaceManager?.destroyWorkspace(this.id);
|
||||
// ... cleanup
|
||||
}
|
||||
}
|
||||
|
||||
// In tests
|
||||
afterEach(() => session.destroy());
|
||||
```
|
||||
|
||||
**Why this is wrong:**
|
||||
- Production class polluted with test-only code
|
||||
- Dangerous if accidentally called in production
|
||||
- Violates YAGNI and separation of concerns
|
||||
- Confuses object lifecycle with entity lifecycle
|
||||
|
||||
**The fix:**
|
||||
```typescript
|
||||
// ✅ GOOD: Test utilities handle test cleanup
|
||||
// Session has no destroy() - it's stateless in production
|
||||
|
||||
// In test-utils/
|
||||
export async function cleanupSession(session: Session) {
|
||||
const workspace = session.getWorkspaceInfo();
|
||||
if (workspace) {
|
||||
await workspaceManager.destroyWorkspace(workspace.id);
|
||||
}
|
||||
}
|
||||
|
||||
// In tests
|
||||
afterEach(() => cleanupSession(session));
|
||||
```
|
||||
|
||||
### Gate Function
|
||||
|
||||
```
|
||||
BEFORE adding any method to production class:
|
||||
Ask: "Is this only used by tests?"
|
||||
|
||||
IF yes:
|
||||
STOP - Don't add it
|
||||
Put it in test utilities instead
|
||||
|
||||
Ask: "Does this class own this resource's lifecycle?"
|
||||
|
||||
IF no:
|
||||
STOP - Wrong class for this method
|
||||
```
|
||||
|
||||
## Anti-Pattern 3: Mocking Without Understanding
|
||||
|
||||
**The violation:**
|
||||
```typescript
|
||||
// ❌ BAD: Mock breaks test logic
|
||||
test('detects duplicate server', () => {
|
||||
// Mock prevents config write that test depends on!
|
||||
vi.mock('ToolCatalog', () => ({
|
||||
discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
|
||||
}));
|
||||
|
||||
await addServer(config);
|
||||
await addServer(config); // Should throw - but won't!
|
||||
});
|
||||
```
|
||||
|
||||
**Why this is wrong:**
|
||||
- Mocked method had side effect test depended on (writing config)
|
||||
- Over-mocking to "be safe" breaks actual behavior
|
||||
- Test passes for wrong reason or fails mysteriously
|
||||
|
||||
**The fix:**
|
||||
```typescript
|
||||
// ✅ GOOD: Mock at correct level
|
||||
test('detects duplicate server', () => {
|
||||
// Mock the slow part, preserve behavior test needs
|
||||
vi.mock('MCPServerManager'); // Just mock slow server startup
|
||||
|
||||
await addServer(config); // Config written
|
||||
await addServer(config); // Duplicate detected ✓
|
||||
});
|
||||
```
|
||||
|
||||
### Gate Function
|
||||
|
||||
```
|
||||
BEFORE mocking any method:
|
||||
STOP - Don't mock yet
|
||||
|
||||
1. Ask: "What side effects does the real method have?"
|
||||
2. Ask: "Does this test depend on any of those side effects?"
|
||||
3. Ask: "Do I fully understand what this test needs?"
|
||||
|
||||
IF depends on side effects:
|
||||
Mock at lower level (the actual slow/external operation)
|
||||
OR use test doubles that preserve necessary behavior
|
||||
NOT the high-level method the test depends on
|
||||
|
||||
IF unsure what test depends on:
|
||||
Run test with real implementation FIRST
|
||||
Observe what actually needs to happen
|
||||
THEN add minimal mocking at the right level
|
||||
|
||||
Red flags:
|
||||
- "I'll mock this to be safe"
|
||||
- "This might be slow, better mock it"
|
||||
- Mocking without understanding the dependency chain
|
||||
```
|
||||
|
||||
## Anti-Pattern 4: Incomplete Mocks
|
||||
|
||||
**The violation:**
|
||||
```typescript
|
||||
// ❌ BAD: Partial mock - only fields you think you need
|
||||
const mockResponse = {
|
||||
status: 'success',
|
||||
data: { userId: '123', name: 'Alice' }
|
||||
// Missing: metadata that downstream code uses
|
||||
};
|
||||
|
||||
// Later: breaks when code accesses response.metadata.requestId
|
||||
```
|
||||
|
||||
**Why this is wrong:**
|
||||
- **Partial mocks hide structural assumptions** - You only mocked fields you know about
|
||||
- **Downstream code may depend on fields you didn't include** - Silent failures
|
||||
- **Tests pass but integration fails** - Mock incomplete, real API complete
|
||||
- **False confidence** - Test proves nothing about real behavior
|
||||
|
||||
**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
|
||||
|
||||
**The fix:**
|
||||
```typescript
|
||||
// ✅ GOOD: Mirror real API completeness
|
||||
const mockResponse = {
|
||||
status: 'success',
|
||||
data: { userId: '123', name: 'Alice' },
|
||||
metadata: { requestId: 'req-789', timestamp: 1234567890 }
|
||||
// All fields real API returns
|
||||
};
|
||||
```
|
||||
|
||||
### Gate Function
|
||||
|
||||
```
|
||||
BEFORE creating mock responses:
|
||||
Check: "What fields does the real API response contain?"
|
||||
|
||||
Actions:
|
||||
1. Examine actual API response from docs/examples
|
||||
2. Include ALL fields system might consume downstream
|
||||
3. Verify mock matches real response schema completely
|
||||
|
||||
Critical:
|
||||
If you're creating a mock, you must understand the ENTIRE structure
|
||||
Partial mocks fail silently when code depends on omitted fields
|
||||
|
||||
If uncertain: Include all documented fields
|
||||
```
|
||||
|
||||
## Anti-Pattern 5: Integration Tests as Afterthought
|
||||
|
||||
**The violation:**
|
||||
```
|
||||
✅ Implementation complete
|
||||
❌ No tests written
|
||||
"Ready for testing"
|
||||
```
|
||||
|
||||
**Why this is wrong:**
|
||||
- Testing is part of implementation, not optional follow-up
|
||||
- TDD would have caught this
|
||||
- Can't claim complete without tests
|
||||
|
||||
**The fix:**
|
||||
```
|
||||
TDD cycle:
|
||||
1. Write failing test
|
||||
2. Implement to pass
|
||||
3. Refactor
|
||||
4. THEN claim complete
|
||||
```
|
||||
|
||||
## When Mocks Become Too Complex
|
||||
|
||||
**Warning signs:**
|
||||
- Mock setup longer than test logic
|
||||
- Mocking everything to make test pass
|
||||
- Mocks missing methods real components have
|
||||
- Test breaks when mock changes
|
||||
|
||||
**your human partner's question:** "Do we need to be using a mock here?"
|
||||
|
||||
**Consider:** Integration tests with real components often simpler than complex mocks
|
||||
|
||||
## TDD Prevents These Anti-Patterns
|
||||
|
||||
**Why TDD helps:**
|
||||
1. **Write test first** → Forces you to think about what you're actually testing
|
||||
2. **Watch it fail** → Confirms test tests real behavior, not mocks
|
||||
3. **Minimal implementation** → No test-only methods creep in
|
||||
4. **Real dependencies** → You see what the test actually needs before mocking
|
||||
|
||||
**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Anti-Pattern | Fix |
|
||||
|--------------|-----|
|
||||
| Assert on mock elements | Test real component or unmock it |
|
||||
| Test-only methods in production | Move to test utilities |
|
||||
| Mock without understanding | Understand dependencies first, mock minimally |
|
||||
| Incomplete mocks | Mirror real API completely |
|
||||
| Tests as afterthought | TDD - tests first |
|
||||
| Over-complex mocks | Consider integration tests |
|
||||
|
||||
## Red Flags
|
||||
|
||||
- Assertion checks for `*-mock` test IDs
|
||||
- Methods only called in test files
|
||||
- Mock setup is >50% of test
|
||||
- Test fails when you remove mock
|
||||
- Can't explain why mock is needed
|
||||
- Mocking "just to be safe"
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Mocks are tools to isolate, not things to test.**
|
||||
|
||||
If TDD reveals you're testing mock behavior, you've gone wrong.
|
||||
|
||||
Fix: Test real behavior or question why you're mocking at all.
|
||||
Reference in New Issue
Block a user