devflow-kit 0.9.0 → 1.0.0

package/shared/skills/self-review/references/patterns.md

@@ -0,0 +1,405 @@
+# Self-Review Patterns
+
+Correct patterns for thorough self-review organized by the 9 pillars.
+
+---
+
+## 9-Pillar Evaluation
+
+For each pillar, ask:
+
+| Pillar | Key Questions |
+|--------|---------------|
+| Design | Does this follow existing patterns? Is it maintainable? |
+| Functionality | Does it meet requirements? Handle edge cases? |
+| Security | Is input validated? Auth checked? Data protected? |
+| Complexity | Can someone understand this in 5 minutes? |
+| Error Handling | Are errors handled with Result types? Logged? |
+| Tests | Is behavior tested? Coverage adequate? |
+| Naming | Are names clear, consistent, domain-aligned? |
+| Consistency | Does this match existing patterns? |
+| Documentation | Are complex parts explained? API documented? |
+
+---
+
+## Issue Classification
+
+| Priority | Action | Examples |
+|----------|--------|----------|
+| P0 (CRITICAL) | Fix immediately | Security holes, data loss, broken functionality |
+| P1 (HIGH) | Fix before returning | Bugs, missing validation, error handling gaps |
+| P2 (MEDIUM) | Fix or document | Style, minor improvements, complexity |
+| P3 (LOW) | Note for future | Nice-to-haves, minor naming |
+
+---
+
+## P0 Pillars (MUST Fix)
+
+### 1. Design - Correct Patterns
+
+**Fix Pattern**: Refactor to match existing architecture. Extract responsibilities. Use dependency injection.
+
+```typescript
+// GOOD: Repository pattern with proper layering
+class UserController {
+  constructor(private userService: UserService) {}
+
+  async getUser(req, res) {
+    const result = await this.userService.findById(req.params.id);
+    if (!result.ok) return res.status(404).json({ error: result.error });
+    return res.json(result.value);
+  }
+}
+
+// GOOD: Single responsibility, focused class
+class UserRepository {
+  constructor(private db: Database) {}
+
+  async findById(id: string): Promise<Result<User, Error>> {
+    // Only handles user data access
+  }
+}
+
+// GOOD: Dependency injection
+class UserService {
+  constructor(
+    private repository: UserRepository,
+    private logger: Logger
+  ) {}
+}
+```
+
+---
+
+### 2. Functionality - Correct Patterns
+
+**Fix Pattern**: Add null checks, use transactions for atomic operations, verify loop bounds.
+
+```typescript
+// GOOD: Proper null handling
+function getDisplayName(user: User): string {
+  return user.profile?.displayName ?? user.email ?? 'Anonymous';
+}
+
+// GOOD: Atomic transaction
+await db.transaction(async (tx) => {
+  const balance = await tx.getBalance(userId);
+  if (balance < amount) {
+    throw new InsufficientFundsError();
+  }
+  await tx.withdraw(userId, amount);
+});
+
+// GOOD: Correct loop bounds
+for (let i = 0; i < array.length; i++) {
+  process(array[i]);
+}
+```
+
+---
+
+### 3. Security - Correct Patterns
+
+**Fix Pattern**: Use parameterized queries, escape user input, use environment variables, add auth middleware.
+
+```typescript
+// GOOD: Parameterized query
+const user = await db.query(
+  'SELECT * FROM users WHERE email = ?',
+  [email]
+);
+
+// GOOD: Safe command execution
+import { execFile } from 'child_process';
+execFile('ls', [sanitizedPath], callback);
+
+// GOOD: Environment variable for secrets
+const API_KEY = process.env.API_KEY;
+if (!API_KEY) throw new Error('API_KEY required');
+
+// GOOD: Auth middleware
+app.delete('/api/users/:id', authMiddleware, adminOnly, async (req, res) => {
+  await deleteUser(req.params.id);
+});
+```
+
+---
+
+## P1 Pillars (SHOULD Fix)
+
+### 4. Complexity - Correct Patterns
+
+**Fix Pattern**: Extract functions, use early returns, define named constants.
+
+```typescript
+// GOOD: Early returns reduce nesting
+function processItem(item: Item): Result<ProcessedItem, Error> {
+  if (!item) return Err('Item required');
+  if (!item.isValid) return Err('Invalid item');
+  if (!item.isActive) return Err('Item not active');
+
+  return Ok(transformItem(item));
+}
+
+// GOOD: Named constants
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const STATUS = { PENDING: 1, ACTIVE: 2, COMPLETED: 3 } as const;
+
+setTimeout(callback, ONE_DAY_MS);
+if (status === STATUS.COMPLETED) { }
+
+// GOOD: Extracted function
+function calculateTotal(items: Item[]): number {
+  return items
+    .filter(item => item.isActive)
+    .reduce((sum, item) => sum + item.price, 0);
+}
+```
+
+---
+
+### 5. Error Handling - Correct Patterns
+
+**Fix Pattern**: Always handle or rethrow errors, include context in messages, use try/finally for cleanup.
+
+```typescript
+// GOOD: Handle or rethrow
+try {
+  await riskyOperation();
+} catch (e) {
+  logger.error('Operation failed', { error: e, context: operationContext });
+  throw new OperationError('Failed to complete operation', { cause: e });
+}
+
+// GOOD: Descriptive error message
+throw new ValidationError(`Invalid email format: ${email}`, {
+  field: 'email',
+  value: email,
+  expected: 'valid email address'
+});
+
+// GOOD: Resource cleanup with try/finally
+const file = await openFile(path);
+try {
+  await processFile(file);
+} finally {
+  await file.close();
+}
+```
+
+---
+
+### 6. Tests - Correct Patterns
+
+**Fix Pattern**: Add tests for all new functions, test behavior not mocks, cover edge cases.
+
+```typescript
+// GOOD: Testing behavior
+describe('createUser', () => {
+  it('returns created user with generated id', async () => {
+    const result = await createUser({ name: 'Test', email: 'test@example.com' });
+
+    expect(result.ok).toBe(true);
+    expect(result.value.id).toBeDefined();
+    expect(result.value.name).toBe('Test');
+  });
+
+  it('returns error for duplicate email', async () => {
+    await createUser({ name: 'First', email: 'test@example.com' });
+    const result = await createUser({ name: 'Second', email: 'test@example.com' });
+
+    expect(result.ok).toBe(false);
+    expect(result.error.type).toBe('DuplicateEmail');
+  });
+});
+
+// GOOD: Edge case coverage
+describe('divide', () => {
+  it('divides positive numbers', () => {
+    expect(divide(10, 2)).toBe(5);
+  });
+
+  it('returns error for division by zero', () => {
+    const result = divide(10, 0);
+    expect(result.ok).toBe(false);
+    expect(result.error.type).toBe('DivisionByZero');
+  });
+
+  it('handles negative numbers', () => {
+    expect(divide(-10, 2)).toBe(-5);
+  });
+});
+```
+
+---
+
+## P2 Pillars (FIX if Time Permits)
+
+### 7. Naming - Correct Patterns
+
+**Fix Pattern**: Rename to be descriptive and accurate.
+
+```typescript
+// GOOD: Descriptive names
+const currentDate = new Date();
+const recentItems = items.filter(item => item.timestamp > currentDate);
+const totalPrice = recentItems.reduce((sum, item) => sum + item.price, 0);
+
+// GOOD: Accurate function name
+function getAllUsers(): User[] {
+  return db.users.findAll();
+}
+
+function getUserById(id: string): Result<User, NotFoundError> {
+  return db.users.findById(id);
+}
+```
+
+---
+
+### 8. Consistency - Correct Patterns
+
+**Fix Pattern**: Match existing patterns, follow established conventions.
+
+```typescript
+// GOOD: Consistent with codebase pattern
+// Existing code uses Result types
+function existingFunction(): Result<User, Error> { }
+
+// Your code also uses Result types
+function yourFunction(): Result<Order, OrderError> {
+  const validation = validateOrder(data);
+  if (!validation.ok) return Err(validation.error);
+
+  return Ok(createOrder(validation.value));
+}
+
+// GOOD: Matching import organization
+// Match existing file's import order
+import { z } from 'zod';
+
+import { Result, Ok, Err } from '@/lib/result';
+import { User, Order } from '@/types';
+import { userRepository } from '@/repositories';
+```
+
+---
+
+### 9. Documentation - Correct Patterns
+
+**Fix Pattern**: Add JSDoc to public APIs, explain complex algorithms, remove outdated comments.
+
+```typescript
+// GOOD: Documented complex function
+/**
+ * Calculate prorated billing amount for plan changes.
+ *
+ * @param plan - The new plan to prorate to
+ * @param start - Start date of billing period
+ * @param end - End date of billing period
+ * @param previous - Previous plan (for upgrade/downgrade calculation)
+ * @returns Prorated amount in cents
+ *
+ * @example
+ * const amount = calculateProratedBilling(premiumPlan, startDate, endDate, basicPlan);
+ */
+export function calculateProratedBilling(
+  plan: Plan,
+  start: Date,
+  end: Date,
+  previous: Plan
+): number {
+  // Calculate remaining days in billing period
+  const remainingDays = differenceInDays(end, new Date());
+  const totalDays = differenceInDays(end, start);
+
+  // Pro-rate the price difference
+  const priceDifference = plan.price - previous.price;
+  return Math.round((priceDifference * remainingDays) / totalDays);
+}
+
+// GOOD: Accurate comment
+// Returns the user's preferred display name, falling back to username
+function getDisplayName(user: User): string {
+  return user.displayName ?? user.username;
+}
+```
+
+---
+
+## Decision Tree
+
+```
+START
+  |
+  v
++------------------+
+| Evaluate P0      |
+| (Design,         |
+|  Functionality,  |
+|  Security)       |
++--------+---------+
+         |
+    Issues found?
+    +----+----+
+   YES       NO
+    |         |
+    v         |
++---------+   |
+| Fixable?|   |
++----+----+   |
+  +--+--+     |
+ YES   NO     |
+  |     |     |
+  v     v     |
+ FIX   STOP   |
+  |   REPORT  |
+  |   BLOCKER |
+  |           |
+  +-----+-----+
+        |
+        v
++------------------+
+| Evaluate P1      |
+| (Complexity,     |
+|  Error Handling, |
+|  Tests)          |
++--------+---------+
+         |
+    Issues found?
+    +----+----+
+   YES       NO
+    |         |
+    v         |
+   FIX        |
+    |         |
+    +----+----+
+         |
+         v
++------------------+
+| Evaluate P2      |
+| (Naming,         |
+|  Consistency,    |
+|  Documentation)  |
++--------+---------+
+         |
+    Issues found?
+    +----+----+
+   YES       NO
+    |         |
+    v         |
+ FIX IF       |
+ TIME         |
+    |         |
+    +----+----+
+         |
+         v
+      RETURN
+   WITH REPORT
+```
+
+---
+
+## Quick Reference
+
+See [violations.md](violations.md) for anti-patterns and [report-template.md](report-template.md) for self-review format.

package/shared/skills/self-review/references/report-template.md

@@ -0,0 +1,253 @@
+# Self-Review Report Template
+
+Use this template when generating your self-review report.
+
+---
+
+## Report Format
+
+```markdown
+## Self-Review Report
+
+### Task
+{Brief description of what was implemented}
+
+### Files Changed
+- `path/to/file.ts` - {what changed}
+- `path/to/test.ts` - {what changed}
+
+---
+
+### P0 Pillars (MUST Fix)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Design | PASS/FIXED | {details if fixed} |
+| Functionality | PASS/FIXED | {details if fixed} |
+| Security | PASS/FIXED | {details if fixed} |
+
+**Fixes Applied**:
+- {file:line} - {what was fixed}
+
+---
+
+### P1 Pillars (SHOULD Fix)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Complexity | PASS/FIXED | {details if fixed} |
+| Error Handling | PASS/FIXED | {details if fixed} |
+| Tests | PASS/FIXED | {details if fixed} |
+
+**Fixes Applied**:
+- {file:line} - {what was fixed}
+
+---
+
+### P2 Pillars (FIX if Time Permits)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Naming | PASS/FIXED/SKIP | {details} |
+| Consistency | PASS/FIXED/SKIP | {details} |
+| Documentation | PASS/FIXED/SKIP | {details} |
+
+**Fixes Applied** (if any):
+- {file:line} - {what was fixed}
+
+---
+
+### Summary
+
+**Issues Found**: {total count}
+**Issues Fixed**: {count}
+**Status**: READY / BLOCKED
+
+{If BLOCKED, explain what cannot be fixed and why}
+```
+
+---
+
+## Example Reports
+
+### Example 1: Clean Pass
+
+```markdown
+## Self-Review Report
+
+### Task
+Add user profile update endpoint
+
+### Files Changed
+- `src/routes/users.ts` - added PUT /users/:id/profile endpoint
+- `src/services/user-service.ts` - added updateProfile method
+- `tests/services/user-service.test.ts` - added profile update tests
+
+---
+
+### P0 Pillars (MUST Fix)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Design | PASS | Follows existing route/service pattern |
+| Functionality | PASS | All edge cases handled |
+| Security | PASS | Auth middleware in place, input validated |
+
+---
+
+### P1 Pillars (SHOULD Fix)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Complexity | PASS | Functions under 30 lines |
+| Error Handling | PASS | Uses Result types consistently |
+| Tests | PASS | Happy path, errors, and edges covered |
+
+---
+
+### P2 Pillars (FIX if Time Permits)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Naming | PASS | Clear, descriptive names |
+| Consistency | PASS | Matches existing patterns |
+| Documentation | PASS | JSDoc on public methods |
+
+---
+
+### Summary
+
+**Issues Found**: 0
+**Issues Fixed**: 0
+**Status**: READY
+```
+
+### Example 2: Issues Fixed
+
+```markdown
+## Self-Review Report
+
+### Task
+Implement order cancellation flow
+
+### Files Changed
+- `src/services/order-service.ts` - added cancelOrder method
+- `src/routes/orders.ts` - added DELETE /orders/:id endpoint
+- `tests/services/order-service.test.ts` - added cancellation tests
+
+---
+
+### P0 Pillars (MUST Fix)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Design | PASS | Follows existing patterns |
+| Functionality | FIXED | Added missing status check before cancel |
+| Security | FIXED | Added ownership verification |
+
+**Fixes Applied**:
+- `src/services/order-service.ts:45` - Added check: cannot cancel completed orders
+- `src/routes/orders.ts:78` - Added auth check: user must own the order
+
+---
+
+### P1 Pillars (SHOULD Fix)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Complexity | PASS | Clean, simple logic |
+| Error Handling | FIXED | Changed generic error to specific CancellationError |
+| Tests | FIXED | Added test for already-completed order case |
+
+**Fixes Applied**:
+- `src/services/order-service.ts:52` - Specific error: `OrderCancellationError('Order already completed')`
+- `tests/services/order-service.test.ts:120` - Added: `it('rejects cancellation of completed orders')`
+
+---
+
+### P2 Pillars (FIX if Time Permits)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Naming | PASS | Clear names |
+| Consistency | PASS | Matches existing order methods |
+| Documentation | FIXED | Added JSDoc explaining cancellation rules |
+
+**Fixes Applied**:
+- `src/services/order-service.ts:40` - Added JSDoc documenting cancellation states
+
+---
+
+### Summary
+
+**Issues Found**: 5
+**Issues Fixed**: 5
+**Status**: READY
+```
+
+### Example 3: Blocked
+
+```markdown
+## Self-Review Report
+
+### Task
+Add payment refund capability
+
+### Files Changed
+- `src/services/payment-service.ts` - added refund method
+- `src/routes/payments.ts` - added POST /payments/:id/refund
+
+---
+
+### P0 Pillars (MUST Fix)
+
+| Pillar | Status | Notes |
+|--------|--------|-------|
+| Design | BLOCKED | Requires architectural change (see below) |
+| Functionality | - | Cannot evaluate due to design blocker |
+| Security | - | Cannot evaluate due to design blocker |
+
+---
+
+### Summary
+
+**Issues Found**: 1 (architectural)
+**Issues Fixed**: 0
+**Status**: BLOCKED
+
+**Blocker**: Payment refunds require access to transaction history, but current
+PaymentService has no dependency on TransactionRepository. Adding this dependency
+would require:
+1. Modifying PaymentService constructor (breaking change)
+2. Updating all 15 existing tests
+3. Modifying dependency injection container
+
+This is beyond the scope of self-review fixes. Escalating to orchestrator for
+architectural decision.
+
+**Recommendation**: Refactor PaymentService to accept TransactionRepository
+before implementing refund feature.
+```
+
+---
+
+## Status Definitions
+
+| Status | Meaning |
+|--------|---------|
+| PASS | No issues found for this pillar |
+| FIXED | Issue found and resolved |
+| SKIP | P2 only - issue noted but not fixed due to time |
+| BLOCKED | Cannot fix - requires escalation |
+
+---
+
+## Report Checklist
+
+Before submitting report:
+- [ ] All P0 pillars are PASS or FIXED
+- [ ] All P1 pillars are PASS or FIXED
+- [ ] P2 pillars evaluated (PASS/FIXED/SKIP)
+- [ ] All fixes documented with file:line
+- [ ] Summary accurately reflects status
+- [ ] If BLOCKED, clear explanation provided