devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/software-design/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: software-design
+description: This skill should be used when the user asks to "handle errors", "inject dependencies", "return Result", "make it immutable", "compose with pipes", or implements business logic, error handling, or service composition. Provides Result type patterns, dependency injection, immutability by default, pipe composition, and structured logging for robust application architecture.
+user-invocable: false
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+---
+
+# Core Engineering Patterns
+
+The canonical source of architectural patterns and principles for consistent, high-quality code.
+
+## Iron Law
+
+> **NEVER THROW IN BUSINESS LOGIC** [1][11]
+>
+> All operations that can fail MUST return Result types. Exceptions are allowed
+> ONLY at system boundaries (API handlers, database adapters). Any `throw` statement
+> in business logic is a violation. No exceptions.
+
+## Philosophy
+
+1. **Functional Core, Imperative Shell** [11] — Pure business logic, side effects at boundary
+2. **Explicit Error Handling** [1][8] — Result types, no exceptions in business logic
+3. **Immutability by Default** [7][14] — Return new objects, never mutate
+4. **Dependency Injection** [3] — All deps injected, nothing instantiated internally
+5. **Make Illegal States Unrepresentable** [4][2] — Types enforce invariants at compile time
+6. **Parse, Don't Validate** [12] — Schema transforms at boundaries
+
+---
+
+## Pattern 1: Result Types [1][5][6][18]
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+function createUser(data: unknown): Result<User, ValidationError> {
+  if (!valid(data)) return Err({ type: 'ValidationFailed', details: validate(data).errors });
+  return Ok(buildUser(data));
+}
+// Libraries: neverthrow [18], ts-results [19]. Theory: Moggi [5] + Wadler [6].
+```
+
+## Pattern 2: Dependency Injection [3]
+
+```typescript
+class UserService {
+  constructor(private db: Database, private emailer: EmailService) {}
+  // Test: new UserService(mockDb, mockEmailer) — never new Database() inside [3]
+}
+```
+
+## Pattern 3: Immutability [7][14]
+
+```typescript
+// New object, never mutate input; copy before .sort() [7][14]
+function updateUser(user: User, changes: Partial<User>): User {
+  return { ...user, ...changes };
+}
+```
+
+## Pattern 4: Functional Core, Imperative Shell [11]
+
+```typescript
+// PURE CORE: no I/O, deterministic [11]
+function calculateTotal(items: Item[], taxRate: number): number {
+  return items.reduce((sum, i) => sum + i.price, 0) * (1 + taxRate);
+}
+// IMPERATIVE SHELL: I/O at boundary only [11]
+async function processOrder(id: string): Promise<Result<Order, Error>> {
+  const order = await db.getOrder(id);
+  return Ok(await db.save({ ...order, total: calculateTotal(order.items, 0.1) }));
+}
+```
+
+## Pattern 5: Type Safety [4][2][21]
+
+```typescript
+// Discriminated unions — compiler enforces exhaustiveness [4][21]
+type UserError =
+  | { type: 'NotFound'; userId: string }           // carries full context [2]
+  | { type: 'ValidationFailed'; field: string; message: string };
+
+type Status = 'pending' | 'completed' | 'failed';
+function handleStatus(status: Status): string {
+  switch (status) {
+    case 'pending': return 'Waiting';
+    case 'completed': return 'Done';
+    case 'failed': return 'Error';
+  }  // Exhaustive — no default needed [21]
+}
+```
+
+## Pattern 6: Pipe Composition [20][13]
+
+```typescript
+const pipe = <T>(...fns: Array<(x: T) => T>) => (x: T) => fns.reduce((v, f) => f(v), x);
+const process = pipe(validate, normalize, enrich); // Composition as glue [20][13]
+```
+
+## Pattern 7: Resource Cleanup + Documentation [7]
+
+```typescript
+const handle = await fs.open(path);
+try { return Ok(parse(await handle.readFile())); }
+finally { await handle.close(); }
+
+// ARCHITECTURE: Repository returns domain objects only
+// ARCHITECTURE EXCEPTION: Direct DB for health check — must work if service layer down
+```
+
+---
+
+## Consistency Rules
+
+- Result types: if one method returns Result, ALL must [1]
+- DI: apply consistently throughout [3]
+- Async: single pattern (don't mix callbacks/promises)
+
+## Anti-Patterns
+
+| Pattern | Source |
+|---------|--------|
+| Throwing in business logic — use Result | [1][11] |
+| Silent failures — swallowed catch blocks | [10] |
+| Mutable state — return new objects | [7][14] |
+| Service locator — inject instead | [3] |
+
+### Workaround Labeling (Required)
+
+`HACK:` `MOCK:` `TODO:` `TEMPORARY:` `NOT-PRODUCTION:` `ARCHITECTURE EXCEPTION:`
+
+Unlabeled workarounds are violations. See `references/code-smell-violations.md`.
+
+---
+
+## Extended References
+
+- `references/sources.md` — Full bibliography (25 sources with access links)
+- `references/violations.md` — Violation patterns with citations
+- `references/patterns.md` — Extended correct patterns with citations
+- `references/checklist.md` — Pre-implementation and review checklists
+- `references/code-smell-violations.md` — Fake solutions, deceptive code, magic values
+- `references/detection.md` — Grep patterns for automated detection

package/src/assets/skills/software-design/references/checklist.md

@@ -0,0 +1,259 @@
+# Validation Checklist
+
+Comprehensive checklist for code review and validation against core engineering patterns.
+All items cite `references/sources.md`.
+
+---
+
+## Pre-Implementation Checklist
+
+Before writing code, verify:
+
+- [ ] Understood the existing patterns in the codebase
+- [ ] Identified similar implementations to follow
+- [ ] Determined if Result types are used (and will follow same pattern) [1]
+- [ ] Identified dependencies that need injection [3]
+- [ ] Planned separation of pure logic from side effects [11]
+
+---
+
+## Result Types Checklist [1][5][6]
+
+### Functions That Can Fail [1]
+
+- [ ] All business functions return `Result<T, E>` types [1]
+- [ ] No `throw` statements in business logic [1][11]
+- [ ] Error types are discriminated unions (not generic Error) [2]
+- [ ] Each error type has all context needed to handle it [2]
+- [ ] Async functions return `Promise<Result<T, E>>` [1]
+
+### Exception Boundaries [11]
+
+- [ ] Try/catch ONLY at system boundaries (API handlers, DB adapters) [11]
+- [ ] Boundaries convert exceptions to Result types [11]
+- [ ] HTTP responses derived from Result errors
+- [ ] No silent error swallowing (empty catch blocks) [10]
+
+### Error Handling [1]
+
+- [ ] All Result errors are handled explicitly [1]
+- [ ] No `if (!result.ok) return;` without proper handling [1]
+- [ ] Error propagation preserves context [1]
+- [ ] Logging happens before converting errors
+
+---
+
+## Dependency Injection Checklist [3]
+
+### Constructor Injection [3]
+
+- [ ] All dependencies passed through constructor [3]
+- [ ] No `new` keyword for dependencies inside classes [3]
+- [ ] No imported singletons used directly [3]
+- [ ] No static method calls on external services [3]
+
+### Interfaces [3]
+
+- [ ] Dependencies typed as interfaces, not implementations [3]
+- [ ] Interfaces are small and focused (Interface Segregation) [3]
+- [ ] Mock implementations easy to create [3]
+- [ ] No concrete class imports in business logic [3]
+
+### Testing [3]
+
+- [ ] Can instantiate class with mock dependencies [3]
+- [ ] No test requires real database/network [3]
+- [ ] No environment manipulation in tests
+- [ ] Test setup is < 10 lines [3]
+
+---
+
+## Immutability Checklist [7][14]
+
+### Objects [7][14]
+
+- [ ] All updates return new objects (spread operator) [7]
+- [ ] No direct property assignment on inputs [14]
+- [ ] No `delete` operator on inputs [14]
+- [ ] Nested updates also create new objects [7]
+
+### Arrays [14]
+
+- [ ] No `.push()`, `.pop()`, `.shift()`, `.unshift()` [14]
+- [ ] No `.splice()`, `.reverse()`, `.sort()` on originals [14]
+- [ ] Use `.map()`, `.filter()`, `.reduce()` for transformations [14]
+- [ ] Copy before sorting: `[...arr].sort()` [14]
+
+### State [7][14]
+
+- [ ] No module-level `let` or `var` [14]
+- [ ] No global mutable state [15]
+- [ ] Configuration is frozen after initialization [7]
+- [ ] Caches use immutable entries [14]
+
+---
+
+## Pure Functions Checklist [8][11]
+
+### Business Logic [11]
+
+- [ ] Pure functions have no side effects [8]
+- [ ] Same input always produces same output [8]
+- [ ] No date/time access (inject clock) [8]
+- [ ] No random values (inject generator) [8]
+- [ ] No environment variable access [11]
+
+### Side Effect Isolation [11]
+
+- [ ] I/O operations in wrapper functions (imperative shell) [11]
+- [ ] Pure calculations extracted and tested separately [11]
+- [ ] Side effects clearly documented [11]
+- [ ] Logging/metrics in wrappers, not core logic [11]
+
+### Dependencies [3][8]
+
+- [ ] Time/random injected as dependencies [8]
+- [ ] Environment config loaded once at startup [3]
+- [ ] File system access at boundaries only [11]
+- [ ] Network calls at boundaries only [11]
+
+---
+
+## Type Safety Checklist [4][2][21][22]
+
+### Strict Types [22]
+
+- [ ] No `any` types (use `unknown` for dynamic data) [22]
+- [ ] All function parameters typed [22]
+- [ ] All return types explicit [22]
+- [ ] Strict null checks enabled [22]
+
+### Pattern Matching [4][21]
+
+- [ ] Switch statements are exhaustive [21]
+- [ ] Discriminated unions for state/variants [4]
+- [ ] No default case that hides missing patterns [21]
+- [ ] Type guards for runtime narrowing [21]
+
+### Type Design [4][2]
+
+- [ ] Domain types prevent primitive obsession [2]
+- [ ] Branded types for IDs that shouldn't mix [4]
+- [ ] Optional fields explicit (`field?: Type`)
+- [ ] Readonly where appropriate [7]
+
+---
+
+## Error Type Design Checklist [1][2]
+
+### Discriminated Unions [2]
+
+- [ ] Each error type has a `type` discriminator [1]
+- [ ] Error types include all context needed [2]
+- [ ] Related errors grouped in union types [2]
+- [ ] Error unions are exhaustive [4]
+
+### Error Information [1][2]
+
+- [ ] Error messages are actionable [1]
+- [ ] Technical details preserved for logging [1]
+- [ ] User-facing messages are sanitized
+- [ ] Error codes are unique and documented [2]
+
+---
+
+## Resource Cleanup Checklist [7]
+
+### File/Connection Handling [7]
+
+- [ ] All file handles closed in `finally` [7]
+- [ ] All connections released in `finally` [7]
+- [ ] Using context managers (Python) or `using` (TS) [7]
+- [ ] Pool resources released after use [7]
+
+### Subscriptions/Timers [7]
+
+- [ ] Event listeners removed on cleanup [7]
+- [ ] Intervals cleared when done [7]
+- [ ] Timeouts cleared if operation completes early [7]
+- [ ] Subscription manager for complex lifecycles [7]
+
+### Memory [7][15]
+
+- [ ] Large data structures released when done [7]
+- [ ] Caches have size limits or TTL [15]
+- [ ] Circular references avoided [7]
+- [ ] WeakMap/WeakSet for object keys [7]
+
+---
+
+## API Consistency Checklist [1][3]
+
+### Error Handling Pattern [1]
+
+- [ ] Same error handling pattern across module [1]
+- [ ] All methods return Result OR all throw (not mixed) [1]
+- [ ] Error types consistent across related methods [1]
+- [ ] HTTP error mapping centralized [11]
+
+### Async Pattern [3]
+
+- [ ] Single async pattern (async/await preferred) [3]
+- [ ] No mixing callbacks and promises [3]
+- [ ] All async calls awaited (no fire-and-forget) [10]
+- [ ] Promise.all for parallel operations
+
+### Naming
+
+- [ ] Consistent naming across codebase
+- [ ] PascalCase for types/classes
+- [ ] camelCase for functions/variables
+- [ ] SCREAMING_SNAKE_CASE for constants
+
+---
+
+## Architecture Documentation Checklist
+
+### Code Comments
+
+- [ ] Public APIs have JSDoc/docstrings
+- [ ] Complex algorithms explained
+- [ ] Non-obvious decisions documented [13]
+- [ ] Architecture boundaries marked
+
+### Exceptions/Workarounds
+
+- [ ] All workarounds labeled (HACK:, TODO:, TEMPORARY:)
+- [ ] Architecture exceptions have justification
+- [ ] Technical debt has tracking ticket
+- [ ] Deadlines on temporary solutions
+
+---
+
+## Anti-Pattern Checklist [1][3][7][14]
+
+Verify NONE of these exist:
+
+- [ ] No hardcoded responses simulating functionality
+- [ ] No silent error swallowing [10]
+- [ ] No unlabeled magic values [9]
+- [ ] No global mutable state [14][15]
+- [ ] No tight coupling to concrete implementations [3]
+- [ ] No mixing error handling patterns [1]
+- [ ] No fire-and-forget async calls [10]
+- [ ] No resource leaks [7]
+
+---
+
+## Final Review Checklist
+
+Before considering code complete:
+
+- [ ] All tests pass
+- [ ] No TypeScript errors
+- [ ] No ESLint warnings
+- [ ] Code matches existing patterns
+- [ ] Documentation updated
+- [ ] No TODO without ticket
+- [ ] No console.log in production code [11]
+- [ ] No commented-out code

package/src/assets/skills/software-design/references/code-smell-violations.md

@@ -0,0 +1,189 @@
+# Code Smell Violations Reference
+
+Extended examples of fake solutions, unlabeled workarounds, deceptive code, and magic values.
+All examples cite `references/sources.md`.
+
+---
+
+## 1. Hardcoded Data (FAKE SOLUTIONS) [10]
+
+"Clean Code" [10] identifies this as a fundamental form of deception. Martin's maxim
+"don't lie to your colleagues" applies equally to code that pretends to be real.
+
+### Violation: Mock data masquerading as real functionality
+
+```typescript
+async function fetchRecommendations(userId: string): Promise<Product[]> {
+  // TODO: Connect to recommendation engine
+  return [
+    { id: "1", name: "Product 1", price: 99.99 },
+    { id: "2", name: "Product 2", price: 149.99 }
+  ];
+}
+```
+
+**Problem**: Returns static data instead of fetching from actual service. Caller has no idea
+this is a fake [10].
+
+### Correct: Honest implementation with Result type [1]
+
+```typescript
+async function getUserProfile(userId: string): Promise<Result<UserProfile, Error>> {
+  try {
+    const response = await api.get(`/users/${userId}`);
+    return { ok: true, value: response.data };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+```
+
+### Correct: Clearly labeled mock for testing
+
+```typescript
+// MOCK: For development only, not production-ready
+async function getUserProfileMock(userId: string): Promise<UserProfile> {
+  return { id: userId, name: "Test User", email: "test@example.com" };
+}
+```
+
+---
+
+## 2. Missing Labels (UNDOCUMENTED WORKAROUNDS) [13]
+
+Hickey's "Simple Made Easy" [13] defines complecting as interleaving concerns.
+Undocumented workarounds complect the accidental with the essential.
+
+### Violation: Temporary fix without documentation
+
+```typescript
+async function syncData() {
+  await sleep(1000); // Wait for previous operation
+  await performSync();
+}
+```
+
+### Correct: Clearly labeled workaround with rationale
+
+```typescript
+function processPayment(amount: number): boolean {
+  // TEMPORARY: Validation disabled until payment gateway integration complete
+  // TODO: Add amount validation, currency checks, fraud detection
+  // Target: Sprint 23 (2025-11-15)
+  // Ticket: PAY-456
+  return true;
+}
+```
+
+### Correct: Documented hack with root cause
+
+```typescript
+async function syncData() {
+  // HACK: Sleep required due to race condition in legacy sync system
+  // Root cause: Event system doesn't guarantee order
+  // Proper fix: Implement event sequencing (3-week effort)
+  // Ticket: SYNC-789
+  await sleep(1000);
+  await performSync();
+}
+```
+
+---
+
+## 3. Fake Functionality (DECEPTIVE CODE) [10]
+
+"Clean Code" Ch.7 [10] specifically warns against functions that pretend to work.
+Result types [1] give us an honest way to say "not implemented yet."
+
+### Violation: Fake error handling with swallowed exception
+
+```typescript
+async function sendEmail(to: string, subject: string, body: string): Promise<void> {
+  try {
+    // TODO: Implement SMTP
+    console.log(`Email sent to ${to}`);
+  } catch (error) {
+    // Ignore errors — caller thinks this worked [10]
+  }
+}
+```
+
+### Correct: Honest unimplemented function [1]
+
+```typescript
+function validateEmail(email: string): Result<boolean, Error> {
+  return {
+    ok: false,
+    error: new Error('NOT-IMPLEMENTED: Email validation pending regex pattern approval')
+  };
+}
+```
+
+---
+
+## 4. Magic Values (UNEXPLAINED CONSTANTS) [9]
+
+Bloch's "Effective Java" Item 72 [9] identifies unexplained constants as a readability
+and maintenance hazard. Named constants make the domain model explicit [2].
+
+### Violation: Magic numbers
+
+```typescript
+function calculateDiscount(price: number, userLevel: number): number {
+  if (userLevel >= 5) return price * 0.15;  // What is 5? What is 0.15? [9]
+  return 0;
+}
+```
+
+### Correct: Named constants with documentation [2][9]
+
+```typescript
+// Domain constants named for their business meaning [2]
+const USER_LEVEL_THRESHOLD = { PREMIUM: 5 } as const;
+const DISCOUNT_RATE = { PREMIUM: 0.15 } as const;
+
+function calculateDiscount(price: number, userLevel: number): number {
+  if (userLevel >= USER_LEVEL_THRESHOLD.PREMIUM) return price * DISCOUNT_RATE.PREMIUM;
+  return 0;
+}
+```
+
+---
+
+## 5. Type Escape Hatches (BYPASSING THE TYPE SYSTEM) [4][22]
+
+Minsky's "Making Illegal States Unrepresentable" [4] and TypeScript strict mode [22]
+are both undermined by unchecked type assertions.
+
+### Violation: as-casting without validation
+
+```typescript
+// VIOLATION: Bypasses all type safety [4][22]
+const user = response.data as User;  // No runtime check
+const name = user!.profile!.name!;   // Assumes structure that may not exist [22]
+```
+
+### Correct: Schema validation at boundary [12]
+
+```typescript
+// Parse, don't validate [12] — schema enforces the shape at the boundary
+const userResult = UserSchema.safeParse(response.data);
+if (!userResult.success) {
+  return Err({ type: 'InvalidResponse', details: userResult.error });
+}
+const user = userResult.data;  // Typed and verified [12]
+```
+
+---
+
+## Detection Quick Reference
+
+Code passes smell check when:
+
+- No hardcoded return data in business logic [10]
+- All workarounds have required labels (`HACK:` `MOCK:` `TODO:` `TEMPORARY:` `NOT-PRODUCTION:` `ARCHITECTURE EXCEPTION:`) [13]
+- All fake/mock code clearly marked [10]
+- Magic values extracted to named constants [9]
+- Functions do what their names promise [10]
+- No unchecked type assertions [4][22]
+- No swallowed exceptions [1][10]