@iowarp/clio-coder 0.3.1 → 0.3.3

package/skills/coding/prototype/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: prototype
+description: Use when a design question should be answered with throwaway code — "does this state model feel right", "sanity-check this logic", "what should this UI look like", "mock something up". Builds a clearly-marked, trivially-runnable, no-persistence prototype, then captures the verdict and discards the code. Not for pre-registered performance experiments; use experiment-protocol. Not for production implementation.
+version: 0.2.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - bash
+  - write
+  - ask_user
+  - artifact
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/prototype
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/mattpocock/skills/tree/main/skills/engineering/prototype
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+---
+
+# Prototype
+
+A prototype is throwaway code that answers a question. Name the question
+first; the question decides the shape.
+
+## Step 1 — Pick the branch
+
+From the user's prompt, the surrounding code, or by asking:
+
+- **"Does this logic / state model feel right?"** → read
+  `references/LOGIC.md`. Build a single shareable HTML file — free-play
+  controls plus guided walkthroughs — that pushes the state machine through
+  the cases that are hard to reason about on paper, drivable by a
+  non-developer.
+- **"What should this look like?"** → read `references/UI.md`. Generate
+  several radically different UI variations on one route, switchable via a
+  URL parameter.
+
+The branches produce very different artifacts; getting this wrong wastes
+the prototype. Ambiguous and the user unreachable → default by neighborhood
+(backend module → logic; page or component → UI) and state the assumption
+at the top of the prototype.
+
+## Step 2 — Build under the prototype rules
+
+1. **Throwaway from day one, marked as such.** Place it near the code it
+   prototypes for, named so a casual reader sees it is not production.
+   Follow the project's existing routing/layout conventions; invent no new
+   top-level structure.
+2. **Trivial to run.** One command in the project's own task runner, or one
+   double-clickable HTML file. No setup thinking required.
+3. **No persistence.** State lives in memory. If the question is itself
+   about a database, use a scratch DB or file named "PROTOTYPE — wipe me".
+4. **Skip the polish.** No tests, no error handling beyond runnable, no
+   abstractions. Speed of learning is the only quality bar.
+5. **Surface the state.** After every action (logic) or variant switch
+   (UI), print or render the full relevant state so the change is visible.
+
+## Step 3 — Capture and discard
+
+When the question is answered:
+
+1. Fold the validated decision into the real code or the relevant plan.
+2. Commit the prototype to a throwaway branch off the main line, and leave
+   a pointer to that branch wherever the work is tracked (issue, plan,
+   handoff).
+3. Record the verdict and the question it settled in the same place.
+4. The main branch keeps only the validated decision — never the prototype.
+
+Done when the verdict is recorded, the pointer exists, and no prototype
+code remains on the working branch.
+
+## Red flags
+
+- A prototype quietly growing tests, error handling, or abstractions — it
+  is becoming production without a decision.
+- Persistence added "just to make it work".
+- The prototype merged to the main line.
+- Code built before the question was stated.

package/skills/coding/prototype/evals.md

@@ -0,0 +1,42 @@
+# Evals — prototype
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — state-model sanity check
+Setup: sanity-check whether the retry state machine in retry.js feels
+right before we build on it.
+
+Fixture:
+```bash
+printf 'const STATES = ["idle", "trying", "backoff", "failed", "done"];\n\nfunction next(state, event) {\n  if (state === "idle" && event === "start") return "trying";\n  if (state === "trying" && event === "ok") return "done";\n  if (state === "trying" && event === "err") return "backoff";\n  if (state === "backoff" && event === "timer") return "trying";\n  if (state === "backoff" && event === "giveup") return "failed";\n  return state;\n}\n\nmodule.exports = { STATES, next };\n' > retry.js
+```
+
+Expected:
+- Question stated first; logic branch chosen; references/LOGIC.md read.
+- Single HTML artifact with free-play plus guided walkthrough cases.
+- Full state surfaced after each action; no persistence.
+- Verdict captured; prototype kept off the main branch.
+
+## S2 — UI exploration
+Prompt: "explore what the dashboard header could look like."
+Expected:
+- UI branch; several genuinely different variants on one route, switchable.
+- Runs from one task-runner command.
+
+## S3 — scope creep
+Setup: mid-prototype, the user says "this looks good, add error handling."
+Expected:
+- Flags the transition: validated decision folds into real code through a
+  normal implementation path; the prototype is not promoted.
+
+## Baseline failure modes to watch for (RED)
+- Building production-shaped code with tests and abstractions.
+- No stated question; prototype answers nothing decidable.
+- Prototype committed to main.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Verdict captured via terminal artifact; code discarded.

package/skills/coding/prototype/references/LOGIC.md

@@ -0,0 +1,67 @@
+# Logic Prototype
+
+A single, self-contained HTML file — a **shareable demo** — that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer — a designer, a PM, a domain expert — and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS — no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language**, not code — buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state** — the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons** — one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs** — a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario — the situation it sets up and what to watch for — and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases — the happy path, a tricky edge case, an attempt at something that should be illegal — the ones hard to reason about on paper.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks — nothing that competes with the state and the buttons.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](../SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps the prototype as a primary source — and being one self-contained file, it stays trivially re-runnable there.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.

package/skills/coding/prototype/references/UI.md

@@ -0,0 +1,112 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes — strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B — a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
+
+Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code — adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
+
+For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow** — cycles to the previous variant (wraps around).
+- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
+- **Right arrow** — cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
+
+Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
+
+### 5. Hand it over
+
+Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"** — that's the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, capture the answer — which variant and why — then capture the prototype the way the [SKILL](../SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch, not into main:
+
+- **Sub-shape A** — fold the winner into the existing page; drop the losing variants and the switcher from main.
+- **Sub-shape B** — promote the winning variant to a real route; drop the throwaway route and the switcher from main.
+
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin — variant components and the switcher left in the main branch rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

package/skills/coding/tdd/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: tdd
+description: Use when the user wants to build a feature or fix a bug test-first, says "TDD", "red-green", or "write the test first", or when a change to tricky logic needs its behavior pinned before implementation. Runs the red → green loop at pre-agreed public seams, one vertical slice at a time. Not for designing benchmark criteria; use experiment-protocol.
+version: 0.2.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - bash
+  - write
+  - edit
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/tdd
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/mattpocock/skills/tree/main/skills/engineering/tdd
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+    - coder
+---
+
+# Test-Driven Development
+
+The red → green loop, run so it produces tests worth keeping. A good test
+verifies behavior through a public interface and reads like a
+specification: "user can checkout with valid cart" names a capability. The
+implementation can change entirely; the test should not.
+
+## Step 1 — Agree the seams
+
+A seam is the public boundary you test at, observing behavior without
+reaching inside. Before writing any test:
+
+1. Read the project's instruction file and existing tests so names and
+   vocabulary match the project's language and test conventions.
+2. Write down the seams under test and confirm them with the user
+   ("What's the public interface, and which seams should we test?").
+
+No test is written at an unconfirmed seam. You cannot test everything;
+agreeing seams up front is what lands the effort on critical paths instead
+of every edge case.
+
+## Step 2 — The loop
+
+Per cycle, exactly:
+
+1. **Red.** Write one failing test for the next thinnest slice of
+   behavior. Run it; watch it fail for the expected reason. A test that
+   passes immediately tested nothing — fix the test before proceeding.
+2. **Green.** Write only enough implementation to pass it. No speculative
+   features, no anticipating future tests.
+3. Run the suite; all green → next slice.
+
+One seam, one test, one minimal implementation per cycle. Refactoring is a
+separate later pass with its own review, not part of this loop.
+
+If the test command cannot execute at all (runner missing, execution
+blocked, environment broken), STOP and report exactly that. A test result
+exists only when a run was observed; never mark a case passed from reading
+the code, and never write "verified" or a pass table for runs that did not
+happen.
+
+Vertical slices only: one test → one implementation → repeat, each test a
+tracer bullet informed by the last cycle. Writing all tests first then all
+code ("horizontal slicing") tests imagined behavior and locks in structure
+before the implementation has taught you anything.
+
+## Anti-patterns (reject the test, not the code)
+
+- **Implementation-coupled**: mocks internal collaborators, tests private
+  functions, or asserts through a side channel (querying the DB instead of
+  the interface). Tell: the test breaks on refactor while behavior is
+  unchanged.
+- **Tautological**: the assertion recomputes the expected value the same
+  way the code does (`expect(add(a,b)).toBe(a+b)`), so it passes by
+  construction. Expected values come from an independent source: a
+  known-good literal, a worked example, the spec.
+- **Mock-everything**: when the tests use heavy mocking or the mocking
+  strategy is in question, read `references/mocking.md`. For worked
+  examples of good versus bad tests, read `references/tests.md`.
+
+## Done when
+
+Every agreed seam has its behaviors covered by tests that were each seen
+red before green, the full suite passes, and no test in the diff trips an
+anti-pattern above. Report which seams are covered and which were
+deliberately left untested.
+
+## Red flags
+
+- A test written after the implementation it claims to drive.
+- A cycle that added two tests or two behaviors at once.
+- Green on first run, accepted without investigation.
+- Tests asserting internal call sequences instead of outcomes.

package/skills/coding/tdd/evals.md

@@ -0,0 +1,41 @@
+# Evals — tdd
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — small feature, test-first
+Setup: add a parseDuration function (strings like "1h30m" to seconds)
+test-first.
+
+Fixture:
+```bash
+printf '{\n  "name": "eval-app",\n  "version": "1.0.0",\n  "private": true,\n  "type": "commonjs",\n  "scripts": {\n    "test": "node --test"\n  }\n}\n' > package.json
+```
+
+Expected:
+- Seams proposed and confirmed before any test.
+- Each cycle: one failing test observed red, then minimal implementation.
+- Expected values are independent literals, not recomputed formulas.
+- Final report names covered and deliberately-uncovered seams.
+
+## S2 — bug fix
+Setup: seeded bug with a reproducing input.
+Expected:
+- First move is a failing test reproducing the bug at a public seam.
+- Fix follows; test goes green; suite stays green.
+
+## S3 — refactor temptation
+Setup: mid-loop, adjacent ugly code invites cleanup.
+Expected:
+- Refactor deferred out of the red-green loop; noted for a separate pass.
+
+## Baseline failure modes to watch for (RED)
+- Implementation written first, tests back-filled.
+- A batch of tests written up front (horizontal slicing).
+- Tests mocking the module under test's internals.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS on re-run under working exec: red observed, then green. The earlier exec-gated run produced a fabricated pass table, which motivated the no-fabricated-verification rule now in the body.

package/skills/coding/tdd/references/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes; prefer a test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/skills/coding/tdd/references/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```