verbolab 0.1.0-alpha.1

package/skills/devops-ci.md

@@ -0,0 +1,82 @@
+---
+name: devops-ci
+description: CI/CD pipelines, deployment strategies, rollback triggers, DORA metrics
+domain: engineering
+subdomain: devops
+---
+
+# DevOps & CI/CD
+
+## Context
+You are setting up CI/CD pipelines, configuring deployment workflows, defining branch protection, or improving delivery performance. Apply these patterns to GitHub Actions workflows and production deployment infrastructure.
+
+## Core Principles
+
+**Trunk-Based Development** (Forsgren, Humble, Kim — *Accelerate*): High-performing teams merge to trunk at least daily. Long-lived branches correlate with lower deployment frequency and higher change failure rates. Keep branches short, merge through PRs with CI gates.
+
+**Deployment Is Not Release** (Humble & Farley — *Continuous Delivery*): Decouple deploying code from exposing features. Deploy frequently behind feature flags; release when ready. This reduces batch size and makes rollbacks trivial.
+
+**DORA Four Key Metrics** (*Accelerate*): Measure delivery performance with deployment frequency (how often you ship), lead time for changes (commit to production), mean time to restore (MTTR when failures happen), and change failure rate (% of deployments causing incidents). Elite teams: multiple deploys/day, <1hr lead time, <1hr MTTR, <5% failure rate.
+
+**Automate the Pain** (*Continuous Delivery*): If a process is painful, do it more often and automate it. Manual gates create bottlenecks and drift. Every step from commit to production should be scripted and repeatable.
+
+## Patterns
+
+**Branch protection rules:**
+Require PR + CI green + 1 reviewer before merge to trunk. Block force-pushes. Require linear history (squash or rebase). This prevents broken code from reaching production.
+
+**Deployment strategies — pick by constraint:**
+- **Blue/green**: instant cutover between identical environments. Use when you need instant rollback. Costs 2x infrastructure.
+- **Canary**: route a small % of traffic to the new version, increase gradually. Use when you need risk-limited validation with real traffic. Requires traffic splitting (feature flags or load balancer rules).
+- **Rolling**: replace instances one at a time. Use for stateless services where zero-downtime matters and infra cost is a constraint.
+
+**Automatic rollback triggers:**
+```yaml
+# Roll back when error rate or latency crosses thresholds
+rollback_conditions:
+  error_rate_threshold: 0.01    # >1% errors → rollback
+  p99_latency_multiplier: 2.0  # >2x baseline p99 → rollback
+  evaluation_window: 5m        # observe for 5 minutes after deploy
+```
+
+**GitHub Actions — fast, cacheable, separated:**
+```yaml
+jobs:
+  lint:
+    steps:
+      - uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: deps-${{ hashFiles('package-lock.json') }}
+      - run: npm ci
+      - run: npm run lint
+  test:
+    needs: [lint]  # fail fast: no tests if lint fails
+    steps:
+      - run: npm ci
+      - run: npm test
+  build:
+    needs: [test]
+    steps:
+      - run: npm run build
+```
+Cache `node_modules` by lockfile hash. Separate lint/test/build into distinct jobs. Fail fast — lint runs first, everything else gates behind it.
+
+## Anti-patterns
+- Manual deploys via SSH or "run this script" — breaks auditability and repeatability.
+- CI pipeline that takes >15 minutes — developers stop waiting and batch changes, increasing risk.
+- No rollback plan before deploying — every deploy must have a known, tested rollback path.
+- Alerting on causes (CPU%, disk%) instead of symptoms (error rate, latency) — causes mislead; symptoms reflect user impact.
+- Environment drift between staging and production — use identical infra-as-code for both.
+
+## Checklist
+- [ ] Branch protection enabled: PR required, CI must pass, 1+ reviewer
+- [ ] Deployment strategy chosen and documented (blue/green, canary, or rolling)
+- [ ] Rollback triggers defined: error rate >1% or p99 >2x baseline
+- [ ] CI jobs separated: lint → test → build, with caching by lockfile hash
+- [ ] DORA metrics tracked: deployment frequency, lead time, MTTR, change failure rate
+- [ ] No manual steps between merge and production deploy
+
+## References
+- *Accelerate* — Nicole Forsgren, Jez Humble, Gene Kim
+- *Continuous Delivery* — Jez Humble, David Farley

package/skills/frontend-design.md

@@ -0,0 +1,69 @@
+---
+name: frontend-design
+description: Distinctive, production-grade frontend interfaces with high design quality
+domain: engineering
+subdomain: frontend
+---
+
+# Frontend Design
+
+## Context
+You are building web UI — components, pages, or full applications. Produce distinctive, polished interfaces that avoid generic AI aesthetics. Apply typographic hierarchy, purposeful motion, and Gestalt grouping to guide the user's eye.
+
+## Core Principles
+
+**Typographic Scale** (Bringhurst, *The Elements of Typographic Style*): Use a ratio-based scale (major third: ×1.25) for type sizes — `12 / 15 / 19 / 24 / 30px`. Consistent ratios create harmony without manual tuning.
+
+**Visual Hierarchy via Size, Weight, Color** (Wathan & Schoger, *Refactoring UI*): Guide attention with three levers in order — size first, then weight, then color. Reserve color for interactive elements and status; don't use it as the primary differentiator.
+
+**Motion Discipline** (Wathan & Schoger, *Refactoring UI*): UI transitions ≤ 300ms with ease-out easing. Entrances (200ms ease-out), exits (150ms ease-in). Slower = sluggish; faster = jarring. Never animate layout properties (width/height) — use transform/opacity only.
+
+**Gestalt Laws** (proximity, similarity, closure): Elements close together are perceived as related — use spacing to form visual groups before reaching for borders or backgrounds. Similar visual treatment implies same category.
+
+**Committed Palette**: One dominant color, one sharp accent, neutrals for surfaces. Timid palettes with 6+ accent colors create visual noise; commit to 2 and own them.
+
+## Patterns
+
+**Typographic scale via CSS variables:**
+```css
+:root {
+  --text-sm: 0.75rem;   /* 12px */
+  --text-base: 1rem;    /* 16px */
+  --text-lg: 1.25rem;   /* 20px */
+  --text-xl: 1.563rem;  /* 25px */
+  --text-2xl: 1.953rem; /* 31px */
+}
+```
+
+**Motion: entrance/exit with transform:**
+```css
+.card { opacity: 0; transform: translateY(8px);
+  transition: opacity 200ms ease-out, transform 200ms ease-out; }
+.card.visible { opacity: 1; transform: translateY(0); }
+```
+
+**Gestalt grouping with spacing:**
+```css
+/* related fields share tight gap; unrelated sections have larger gap */
+.form-group { display: flex; flex-direction: column; gap: 0.5rem; }
+.form-section + .form-section { margin-top: 2rem; }
+```
+
+## Anti-patterns
+- Inter font + purple gradient + white background — the "AI default".
+- Animations on every element — causes motion sickness and hurts performance.
+- Inline styles scattered across components — use CSS variables or utility classes.
+- Fixed pixel widths without responsive breakpoints — always mobile-first.
+- Animating `width`, `height`, or `margin` — causes layout thrash; use `transform` instead.
+
+## Checklist
+- [ ] Font choice is intentional — not Inter/Roboto as default
+- [ ] Color palette defined as CSS variables with dominant + accent
+- [ ] Type sizes follow a consistent ratio-based scale
+- [ ] Motion limited to transform/opacity, duration ≤ 300ms
+- [ ] Responsive at 375px / 768px / 1280px breakpoints
+- [ ] Contrast ratios pass WCAG AA; focus states visible
+
+## References
+- *Refactoring UI* — Adam Wathan & Steve Schoger
+- *The Elements of Typographic Style* — Robert Bringhurst

package/skills/observability.md

@@ -0,0 +1,73 @@
+---
+name: observability
+description: Structured logging, metrics, distributed tracing, alerting on SLIs, OpenTelemetry instrumentation
+domain: engineering
+subdomain: observability
+---
+
+# Observability
+
+## Context
+You are adding logging, metrics, or tracing to a service — or designing alerts, dashboards, or SLOs. Apply these patterns whenever instrumenting code, diagnosing production issues, or setting up monitoring infrastructure.
+
+## Core Principles
+
+**Three Pillars** (Majors, Fong-Jones, Miranda — *Observability Engineering*): Logs tell you *what happened* (discrete events), metrics tell you *how much / how long* (aggregated numbers over time), traces tell you *where time went* (request flow across service boundaries). Each pillar answers a different question — use all three together, not as substitutes.
+
+**Alert on Symptoms, Not Causes** (Google — *Site Reliability Engineering*): Alert on user-facing SLIs — error rate, latency, availability. Never alert on CPU%, disk%, or thread count directly. Causes are for dashboards during investigation; symptoms are what page the oncall. A server at 95% CPU serving all requests within SLO is not an incident.
+
+**Instrument at Boundaries** (OpenTelemetry specification): Place instrumentation at system boundaries — HTTP handlers, outgoing HTTP calls, database queries, queue produce/consume. Business logic internals rarely need spans. Boundary instrumentation captures the signals that matter with minimal noise.
+
+**Structured Logging** (*Observability Engineering*): Every log entry must be a key-value object, never an interpolated string. Required fields: `level`, `timestamp` (ISO 8601), `service`, `traceId`, `msg`. Structured logs are queryable; string-concatenated messages are not.
+
+## Patterns
+
+**Structured log entry:**
+```json
+{
+  "level": "error",
+  "timestamp": "2026-03-27T14:05:32.123Z",
+  "service": "payment-api",
+  "traceId": "abc123def456",
+  "msg": "charge failed",
+  "userId": "u_982",
+  "errorCode": "card_declined"
+}
+```
+Never use `logger.error(\`charge failed for ${userId}\`)` — use `logger.error({ msg: "charge failed", userId })`. String interpolation destroys queryability.
+
+**USE method for resources** (Brendan Gregg): For every resource (CPU, memory, disk, network), measure Utilization (% busy), Saturation (queue depth), and Errors (fault count). This systematically covers resource bottlenecks.
+
+**RED method for services** (Tom Wilkie): For every service endpoint, measure Rate (requests/sec), Errors (failed requests/sec), and Duration (latency distribution). RED gives instant service health at a glance.
+
+**OpenTelemetry boundary instrumentation:**
+```typescript
+// Instrument at HTTP boundary — not inside calculateTotal()
+app.post("/orders", async (req, res) => {
+  const span = tracer.startSpan("POST /orders");
+  const result = await db.query("INSERT INTO orders ...");
+  // db.query is auto-instrumented by otel-plugin-pg
+  span.end();
+});
+```
+
+## Anti-patterns
+- Using user IDs, request IDs, or URLs as metric label values — unbounded cardinality explodes storage and query cost. Use bounded enums (status code, endpoint name, region).
+- Logging inside tight loops — generates noise, hurts performance, buries signal.
+- Alerting on causes like CPU > 80% — leads to false pages and alert fatigue. Alert on SLI breach instead.
+- Tracing every internal function call — creates massive trace trees with no diagnostic value. Trace boundaries only.
+- Unstructured log messages with string concatenation — impossible to filter, aggregate, or correlate.
+
+## Checklist
+- [ ] Logs are structured JSON with `level`, `timestamp`, `service`, `traceId`, `msg`
+- [ ] No string interpolation in log calls — all values passed as key-value fields
+- [ ] Metric labels use bounded enums only — no user IDs, request paths, or unbounded values
+- [ ] HTTP handlers, DB queries, and queue operations have tracing spans
+- [ ] Alerts fire on user-facing symptoms (error rate, latency SLI), not infrastructure causes
+- [ ] USE method applied to resources, RED method applied to service endpoints
+- [ ] `traceId` propagated across service boundaries for distributed correlation
+
+## References
+- *Site Reliability Engineering* — Betsy Beyer, Chris Jones, Jennifer Petoff, Niall Richard Murphy (Google)
+- *Observability Engineering* — Charity Majors, Liz Fong-Jones, George Miranda
+- OpenTelemetry Specification — OpenTelemetry Authors

package/skills/react-nextjs.md

@@ -0,0 +1,76 @@
+---
+name: react-nextjs
+description: Server/client component architecture, data fetching, hydration safety, and Next.js performance patterns
+domain: engineering
+subdomain: frontend
+---
+
+# React & Next.js
+
+## Context
+You are building or modifying a React application using Next.js App Router. Apply server-first rendering, avoid unnecessary client boundaries, fetch data in server components, and use Next.js built-in optimizations for images, fonts, and code splitting.
+
+## Core Principles
+
+**Server-First Component Model** (Next.js docs, Vercel): Every component is a server component by default. Add `'use client'` only when the component needs interactivity, browser APIs, or React hooks. Keep the client boundary as low in the tree as possible — wrap the interactive leaf, not the parent.
+
+**Collocated Data Fetching** (React docs, Meta): Fetch data directly in the server component that needs it using `async/await` — no useEffect, no client-side fetch libraries. Use `Suspense` boundaries to stream async subtrees without blocking the entire page.
+
+**Hydration Determinism** (*Fluent React*, Strimpel): Server-rendered HTML must match the initial client render exactly. Non-deterministic content (dates, random values, user-agent checks) causes hydration mismatches. Move these into client components or use `suppressHydrationWarning`.
+
+**Composition Over Prop Drilling** (React docs, Meta): When props pass through more than two intermediaries, restructure. Use the `children` prop to compose layouts, or lift state to the closest common ancestor.
+
+## Patterns
+
+**Server vs client decision tree:**
+```
+Does the component need hooks, event handlers, or browser APIs?
+  → YES: 'use client' on that component (not the parent)
+  → NO:  Keep as server component — fetch data directly
+```
+
+**Data fetching with Suspense:**
+```tsx
+// page.tsx — server component, no 'use client'
+async function TaskList() {
+  const tasks = await db.tasks.findMany(); // runs on server, zero client JS
+  return <ul>{tasks.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+export default function Page() {
+  return (
+    <Suspense fallback={<TaskListSkeleton />}>
+      <TaskList />
+    </Suspense>
+  );
+}
+```
+
+**Performance optimizations:**
+```tsx
+import Image from 'next/image';        // automatic WebP/AVIF, lazy loading, no CLS
+import { Inter } from 'next/font/google'; // eliminates font CLS, self-hosted
+import dynamic from 'next/dynamic';
+const HeavyChart = dynamic(() => import('./Chart'), { ssr: false }); // client-only bundle
+```
+
+## Anti-patterns
+- Adding `'use client'` at the layout or page level — pushes the entire subtree to the client, losing server rendering benefits.
+- Fetching data in useEffect when the component could be a server component — adds a client-server waterfall.
+- Rendering `new Date()` or `Math.random()` in server components without handling hydration mismatch.
+- Passing props through 3+ intermediate components instead of composing with children or context.
+- Using `<img>` tags instead of `next/image` — loses automatic optimization, lazy loading, and CLS prevention.
+- Importing heavy client-only libraries (chart libs, rich editors) without `dynamic(() => import(...), { ssr: false })`.
+
+## Checklist
+- [ ] `'use client'` only on components that need interactivity — never on pages or layouts
+- [ ] Data fetched in server components, not via useEffect
+- [ ] Suspense boundaries wrap async server components with skeleton fallbacks
+- [ ] No hydration mismatches — non-deterministic values handled in client components
+- [ ] All images use `next/image`, all fonts use `next/font`
+- [ ] Heavy client-only libraries loaded with `dynamic({ ssr: false })`
+- [ ] Props pass through ≤2 levels — deeper needs are composed via children or context
+
+## References
+- *React Documentation* — Meta
+- *Next.js Documentation* — Vercel
+- *Fluent React* — Tejas Kumar (Strimpel)

package/skills/refactoring.md

@@ -0,0 +1,77 @@
+---
+name: refactoring
+description: Code smell detection, safe refactoring patterns, large-scale restructuring
+domain: engineering
+subdomain: code-quality
+---
+
+# Refactoring
+
+## Context
+You are restructuring existing code — improving design without changing behavior. Apply when code smells signal structural problems, or when a large refactor needs a safe incremental strategy. Every refactoring must preserve all existing tests (green-to-green).
+
+## Core Principles
+
+**Smell-Driven Refactoring** (Fowler, *Refactoring*): Don't refactor by intuition. Identify a specific smell, apply the named refactoring that addresses it, then verify tests still pass. One smell, one move, one commit.
+
+**Seams Over Rewrites** (Feathers, *Working Effectively with Legacy Code*): A seam is a place where you can alter behavior without editing the code at that point. Insert seams (interfaces, dependency injection, config flags) to make untested code testable before restructuring it.
+
+**Mikado Method** (Ellnestam & Brolund): For entangled changes — attempt the target refactoring, note what breaks, revert, then fix prerequisites bottom-up. Build a dependency graph of changes; merge leaves first. Never push a broken intermediate state.
+
+## Patterns
+
+**Smell: Long Method** (>20 lines or >2 levels of nesting)
+Extract Method — pull coherent blocks into named functions:
+```typescript
+// Before: 30-line handler mixing validation, logic, response
+// After:
+const errors = validateInput(req.body);
+if (errors) return res.status(400).json(errors);
+const result = processOrder(req.body);
+return res.json(formatResponse(result));
+```
+
+**Smell: Large Class** (>200 lines or >5 unrelated responsibilities)
+Extract Class — group related fields and methods into a new cohesive unit.
+
+**Smell: Feature Envy** (method uses another class's data more than its own)
+Move Method — relocate to the class whose data it actually needs.
+
+**Smell: Data Clumps** (3+ fields always passed together)
+Extract Class or introduce a Value Object:
+```typescript
+// Before: createUser(street, city, zip, country)
+// After:
+createUser(address: Address)
+```
+
+**Smell: Primitive Obsession** (strings/numbers carrying domain meaning)
+Replace with Value Object — `Email`, `Money`, `TaskId` instead of raw primitives. Validation lives in the constructor.
+
+**Smell: Divergent Change** (one class changes for unrelated reasons)
+Split into cohesive units — each class should have exactly one reason to change (SRP).
+
+**Safe Large Refactor: Strangler Fig**
+Wrap old module behind a new interface, redirect callers gradually, delete old code when traffic reaches zero. Never maintain two active implementations — one is always the canonical path.
+
+**Safe Large Refactor: Seam Insertion**
+Add an interface at the boundary between the code you want to change and its dependents. Dependents program to the interface; you swap the implementation behind it.
+
+## Anti-patterns
+- Big-bang rewrite — replacing a working module in one PR is the highest-risk pattern; use strangler fig instead.
+- Refactoring without tests — if no tests exist, write characterization tests first (Feathers) to lock current behavior.
+- Mixing refactoring with feature work in the same commit — makes rollback impossible and review confusing.
+- Renaming everything for style consistency when only fixing one smell — scope creep undermines safety.
+- Speculative generalization — extracting abstractions for future needs that may never arrive.
+
+## Checklist
+- [ ] Specific smell identified before refactoring started
+- [ ] All existing tests pass before AND after each refactoring step
+- [ ] No behavior change introduced (refactoring only)
+- [ ] Each commit contains exactly one refactoring move
+- [ ] For large refactors: incremental strategy chosen (strangler fig, seam, or mikado)
+- [ ] Characterization tests written for any untested code before restructuring
+
+## References
+- *Refactoring: Improving the Design of Existing Code* — Martin Fowler
+- *Working Effectively with Legacy Code* — Michael Feathers

package/skills/security.md

@@ -0,0 +1,75 @@
+---
+name: security
+description: Auth, vulnerabilities, permissions, trust levels, hardening
+domain: engineering
+subdomain: security
+---
+
+# Security
+
+## Context
+You are working on security-sensitive code: authentication, authorization, input handling, or trust boundaries. Apply defense in depth — validate at every layer, store secrets safely, and model threats before writing code.
+
+## Core Principles
+
+**Validate at System Boundaries** (Anderson, *Security Engineering*): Trust nothing that crosses a trust boundary. Validate and sanitize all external input — user input, API payloads, webhook bodies, file paths — before passing it inward. Internal calls between trusted modules do not need re-validation.
+
+**OWASP Top 10 → Code Patterns** (OWASP Foundation, *OWASP Top 10*):
+- Injection → parameterized queries, never string-concatenated SQL
+- Broken authentication → short-lived tokens (≤1h) + rotation; httpOnly cookies, not localStorage
+- XSS → Content-Security-Policy headers + output encoding; never `innerHTML = userInput`
+- Broken access control → deny by default; check permissions before every data access
+
+**Threat Modeling 4-Question Checklist** (Shostack, *Threat Modeling*): Before implementing auth/permissions code, ask: (1) What are we building? (2) What can go wrong? (3) What do we do about it? (4) Did we do a good job? Document answers in a comment or ADR.
+
+**Least Privilege Per Layer**: Each service, agent, and DB role gets minimum required permissions. An agent that reads tasks must not have write access to secrets. Escalate explicitly, not by default.
+
+**Defense in Depth** (Anderson, *Security Engineering*): No single control is sufficient. Layer validation + parameterized queries + least privilege + audit logging. Assume any one layer can fail.
+
+## Patterns
+
+**Parameterized query (never concatenate):**
+```typescript
+// Safe
+const stmt = db.prepare('SELECT * FROM users WHERE id = ?');
+const user = stmt.get(userId);
+
+// Unsafe — never do this
+const user = db.exec(`SELECT * FROM users WHERE id = '${userId}'`);
+```
+
+**Short-lived token + rotation:**
+```typescript
+// Issue token with short TTL; refresh before expiry
+const token = jwt.sign({ sub: userId }, secret, { expiresIn: '1h' });
+// Store in httpOnly cookie, not localStorage
+res.cookie('token', token, { httpOnly: true, secure: true, sameSite: 'strict' });
+```
+
+**CSP header + output encoding:**
+```typescript
+res.setHeader("Content-Security-Policy", "default-src 'self'");
+// Encode before rendering user content
+const safe = escapeHtml(userInput); // never innerHTML = userInput
+```
+
+## Anti-patterns
+- Logging secrets, tokens, or API keys — even partial values leak.
+- Trusting agent-supplied file paths without validation — path traversal risk.
+- `localStorage` for session tokens — accessible to XSS.
+- Hardcoded credentials anywhere in the codebase.
+- Running agents with `high` trust by default — explicit escalation only.
+- Catching and swallowing auth errors silently.
+
+## Checklist
+- [ ] All user/agent input validated with zod at the boundary
+- [ ] SQL queries use prepared statements
+- [ ] Secrets in environment variables only — not in code or logs
+- [ ] File paths validated against allowed directories
+- [ ] Tokens short-lived (≤1h) and stored in httpOnly cookies
+- [ ] CSP headers set on all HTML responses
+- [ ] Trust level explicitly set per agent/service — not defaulted
+
+## References
+- *Security Engineering* — Ross Anderson
+- *OWASP Top 10* — OWASP Foundation

package/skills/testing.md

@@ -0,0 +1,69 @@
+---
+name: testing
+description: Test strategy, Vitest patterns, mocking, coverage
+domain: engineering
+subdomain: testing
+---
+
+# Testing
+
+## Context
+You are writing or improving tests. Use Vitest as the test runner. Apply the test pyramid ratios, use precise test doubles (not blanket mocks), and follow TDD when adding new behavior.
+
+## Core Principles
+
+**Test Pyramid** (Fowler, cited in *xUnit Test Patterns*): Aim for ~70% unit / ~20% integration / ~10% e2e. Heavy e2e suites are slow and brittle; over-mocked unit tests miss integration bugs. Balance matters.
+
+**Test Double Taxonomy** (Meszaros, *xUnit Test Patterns*): Use the right double for the job — **stub** (returns canned data, no assertions), **spy** (records calls for after-the-fact assertions), **mock** (expectations set upfront, verified on call), **fake** (working lightweight implementation, e.g. in-memory DB). Overusing mocks couples tests to implementation.
+
+**Listen to the Tests** (Freeman & Pryce, *Growing Object-Oriented Software, Guided by Tests*): Hard-to-test code signals bad design. Painful DI = missing abstraction. Deep nesting = missing object. Let test pain guide refactoring.
+
+**Property-Based Testing Trigger**: When a function processes unbounded input (parsers, encoders, validators), write at least one property test: for all valid inputs, invariants hold (e.g., `encode(decode(x)) === x`).
+
+**Isolation as a Constraint**: Each test must pass when run alone (`vitest run <file>`). If it depends on test order, there is shared mutable state to fix.
+
+## Patterns
+
+**Arrange-Act-Assert with descriptive names:**
+```typescript
+it('should return NotFoundError when task id does not exist', () => {
+  // Arrange
+  const repo = createTaskRepo({ db: createDatabase(':memory:') });
+  // Act
+  const result = repo.findById('nonexistent-id');
+  // Assert
+  expect(result).toBeInstanceOf(NotFoundError);
+});
+```
+
+**Spy vs stub distinction:**
+```typescript
+const notifySpy = vi.fn(); // spy: assert it was called
+const getUser = vi.fn().mockReturnValue({ id: '1' }); // stub: returns canned data
+```
+
+**Fake for DB isolation:**
+```typescript
+// Fake: real SQL, but in-memory — no mocking internals
+const db = createDatabase(':memory:');
+runMigrations(db);
+```
+
+## Anti-patterns
+- Testing private methods or internal state — test through the public interface only.
+- Shared mutable state between tests — always reset in `beforeEach`.
+- Mocking the module under test — if you need to mock it, it shouldn't be under test.
+- `test.skip` left in production code — fix or delete.
+- Snapshots for logic tests — use explicit assertions; snapshots are for serialized output only.
+
+## Checklist
+- [ ] Every new function has happy-path + error-path test
+- [ ] Mocks/spies reset in `beforeEach` or `afterEach`
+- [ ] No test depends on another test's state
+- [ ] Temp files and in-memory DBs cleaned up after each test
+- [ ] Correct double type used: stub/spy/mock/fake — not blanket `vi.mock`
+- [ ] `vitest run <file>` passes in isolation
+
+## References
+- *xUnit Test Patterns* — Gerard Meszaros
+- *Growing Object-Oriented Software, Guided by Tests* — Steve Freeman & Nat Pryce