bigpowers 2.2.0 → 2.4.0

package/.pi/skills/define-language/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: define-language
+description: "Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to specs/UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD"."
+---
+
+
+# Define Language
+
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to `specs/UBIQUITOUS_LANGUAGE.md`.
+
+**Distinct from `model-domain` and `deepen-architecture`:** Use this skill to produce a canonical glossary of terms (words and definitions). Use `model-domain` to stress-test a plan through an interview that resolves domain model decisions. Use `deepen-architecture` to find module-level refactoring opportunities in the codebase.
+
+> **HARD GATE** — Ubiquitous language is NOT optional. Every term in the domain that could be misunderstood must be glossed. Ambiguity = rework.
+
+## Process
+
+1. **Scan the conversation** for domain-relevant nouns, verbs, and concepts
+2. **Identify problems**:
+   - Same word used for different concepts (ambiguity)
+   - Different words used for the same concept (synonyms)
+   - Vague or overloaded terms
+3. **Propose a canonical glossary** with opinionated term choices
+4. **Write to `specs/UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+5. **Output a summary** inline in the conversation
+
+## Output Format
+
+Write a `specs/UBIQUITOUS_LANGUAGE.md` file with this structure:
+
+```md
+# Ubiquitous Language
+
+## Order lifecycle
+
+| Term        | Definition                                              | Aliases to avoid      |
+| ----------- | ------------------------------------------------------- | --------------------- |
+| **Order**   | A customer's request to purchase one or more items      | Purchase, transaction |
+| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
+
+## People
+
+| Term         | Definition                                  | Aliases to avoid       |
+| ------------ | ------------------------------------------- | ---------------------- |
+| **Customer** | A person or organization that places orders | Client, buyer, account |
+| **User**     | An authentication identity in the system    | Login, account         |
+
+## Relationships
+
+- An **Invoice** belongs to exactly one **Customer**
+- An **Order** produces one or more **Invoices**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — these are distinct concepts.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear recommendation.
+- **Only include terms relevant for domain experts.** Skip names of modules or classes unless they have domain meaning.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Group terms into multiple tables** when natural clusters emerge. One table is fine if terms are cohesive.
+- **Write an example dialogue.** 3–5 exchanges between a dev and domain expert showing terms used precisely.
+
+## Re-running
+
+When invoked again in the same conversation:
+
+1. Read the existing `specs/UBIQUITOUS_LANGUAGE.md`
+2. Incorporate any new terms from subsequent discussion
+3. Update definitions if understanding has evolved
+4. Re-flag any new ambiguities
+5. Rewrite the example dialogue to incorporate new terms

package/.pi/skills/define-success/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: define-success
+description: "Convert an imperative task statement into explicit "step → verify: <cmd>" pairs before implementation begins. Use before plan-work when success criteria are unclear, when a task lacks verifiable checkpoints, or when user says "how will we know this is done?"."
+---
+
+
+# Define Success
+
+Transform "do X" into "step → verify: <cmd>" pairs. This is the pre-flight check before `plan-work` or `develop-tdd` — it makes success observable and removes ambiguity about when you're done.
+
+> **HARD GATE** — Success criteria must be testable and user-observable. "Code should be fast" is not testable. "Pageload latency < 2s" is testable.
+
+## Why this matters
+
+"Implement user authentication" is not a plan. It has no checkpoints, no evidence requirement, and no way to know if you're done. The Karpathy principle: every step must be independently verifiable with a runnable command. If you can't verify it, you can't prove it works.
+
+## Process
+
+### 1. Read the task statement
+
+Take the task as stated (from conversation, or from `specs/epics/ (see slice-tasks)`, or from `specs/product/SCOPE_LATEST.yaml`).
+
+### 2. Break into observable outcomes
+
+For each thing the task requires, identify:
+- The smallest unit of observable behavior that proves something works
+- The command that proves it
+
+Work at the level of behaviors (what the system does) not implementation steps (how you'll write the code).
+
+### 3. Write the pairs
+
+Format each pair as:
+```
+N. [What must be true] → verify: <runnable command>
+```
+
+Examples:
+
+```
+Task: "Add user registration to the API"
+
+1. POST /users accepts {email, name} and returns {id, email, name} → verify: curl -s -X POST http://localhost:3000/users -H 'Content-Type: application/json' -d '{"email":"test@test.com","name":"Test"}' | jq .id
+2. Duplicate email is rejected with 409 → verify: npm test -- user-registration.test.ts
+3. Missing email is rejected with 400 and descriptive error → verify: npm test -- user-validation.test.ts
+4. Password is hashed (never stored in plaintext) → verify: npm test -- user-security.test.ts
+5. All existing tests still pass → verify: npm test
+```
+
+### 4. Challenge completeness
+
+Ask yourself:
+- Is there any behavior the task requires that isn't covered by a verify step?
+- Is every verify step runnable right now without additional setup?
+- Does the final step verify the whole thing end-to-end?
+
+Add any missing pairs.
+
+### 5. Output
+
+Present the pairs to the user and ask: "Does this capture everything the task requires? Anything missing?"
+
+Once confirmed, these pairs become the skeleton for `plan-work`'s steps. Pass them along when calling `plan-work`.

package/.pi/skills/delegate-task/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: delegate-task
+description: "Delegate one complex task to a single subagent, review its work in two stages before merging back. Sequential — one agent at a time, with oversight. Use when a task is complex and requires careful review before the result is accepted. Distinct from dispatch-agents (no parallelism here; reviewer sees full diff before proceeding)."
+---
+
+
+# Delegate Task
+> **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently.
+
+
+Delegate a single complex task to a subagent with a two-stage review gate before accepting the result. Use when oversight of a single task matters more than speed.
+
+**Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates.
+
+## Process
+
+### 1. Define the task
+
+Before spawning the agent, read `specs/state.yaml` if it exists. Then write a minimal self-contained brief using this template (brief size directly controls token cost and hallucination risk — do not pad):
+
+```
+Goal: [one sentence — specific, measurable outcome]
+In scope: [explicit file or module list]
+Out of bounds: [what NOT to do]
+Constraints: [relevant CONVENTIONS.md rules, existing patterns, test requirements]
+Verify: [runnable command]
+Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply]
+```
+
+Do not include full file contents, full conversation history, or decisions unrelated to this task.
+
+### 2. Spawn the subagent (iterative retrieval, max 3 cycles)
+
+Use the Agent tool with a **fresh context** per spawn. Pass prior decisions only via `specs/state.yaml`.
+
+**Cycle:** dispatch → evaluate output vs goal → refine brief → re-spawn if needed (max 3 cycles).
+
+Include in each brief:
+- All context the agent needs (it starts cold — no shared state)
+- Reference to CONVENTIONS.md constraints
+- The verify command it must run before reporting done
+
+### 3. Stage 1 review — output inspection
+
+When the subagent returns, review its report before looking at the diff:
+- Did it run the verify command? Did it pass?
+- Does it explain what it changed and why?
+- Are there any concerns raised by the agent?
+
+If the report raises red flags, ask the subagent for clarification or re-run with adjusted instructions.
+
+### 4. Stage 2 review — diff inspection
+
+Inspect the actual diff:
+```bash
+git diff main...HEAD
+```
+
+Check:
+- [ ] Changes are scoped to what was asked — nothing extra
+- [ ] No `any`, no `@ts-ignore`, no disabled lint rules
+- [ ] Tests added for new behavior
+- [ ] CONVENTIONS.md compliance (naming, structure, no gh issue creation)
+- [ ] Boy Scout Rule: touched areas are cleaner than before
+
+### 5. Decision
+
+- **Accept**: merge the result into the main working branch
+- **Revise**: send back to the subagent with specific feedback
+- **Reject**: discard and re-approach differently
+
+**After accepting**, append to `specs/state.yaml` under `## Active Decisions`:
+```
+**[task short name]**: [what approach the agent chose and why — one sentence]
+```
+
+Report the decision and rationale to the user.

package/.pi/skills/design-interface/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: design-interface
+description: "Generate multiple radically different interface designs for a module using parallel sub-agents, then compare trade-offs. Based on "Design It Twice" from A Philosophy of Software Design. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice"."
+---
+
+
+# Design Interface
+
+Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+
+> **HARD GATE** — Multiple design options must be explored. Do NOT settle on first idea. Compare trade-offs (UX, complexity, extensibility, performance) before committing.
+
+## Workflow
+
+### 1. Gather Requirements
+
+Before designing, understand:
+
+- [ ] What problem does this module solve?
+- [ ] Who are the callers? (other modules, external users, tests)
+- [ ] What are the key operations?
+- [ ] Any constraints? (performance, compatibility, existing patterns)
+- [ ] What should be hidden inside vs exposed?
+
+Ask: "What does this module need to do? Who will use it?"
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+
+```
+Prompt template for each sub-agent:
+
+Design an interface for: [module description]
+
+Requirements: [gathered requirements]
+
+Constraints for this design: [assign a different constraint to each agent]
+- Agent 1: "Minimize method count - aim for 1-3 methods max"
+- Agent 2: "Maximize flexibility - support many use cases"
+- Agent 3: "Optimize for the most common case"
+- Agent 4: "Take inspiration from [specific paradigm/library]"
+
+Output format:
+1. Interface signature (types/methods)
+2. Usage example (how caller uses it)
+3. What this design hides internally
+4. Trade-offs of this approach
+```
+
+### 3. Present Designs
+
+Show each design with:
+
+1. **Interface signature** — types, methods, params
+2. **Usage examples** — how callers actually use it in practice
+3. **What it hides** — complexity kept internal
+
+Present designs sequentially so user can absorb each approach before comparison.
+
+### 4. Compare Designs
+
+After showing all designs, compare them on:
+
+- **Interface simplicity**: fewer methods, simpler params
+- **General-purpose vs specialized**: flexibility vs focus
+- **Implementation efficiency**: does shape allow efficient internals?
+- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Ease of correct use** vs **ease of misuse**
+
+Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+
+### 5. Synthesize
+
+Often the best design combines insights from multiple options. Ask:
+
+- "Which design best fits your primary use case?"
+- "Any elements from other designs worth incorporating?"
+
+## Evaluation Criteria
+
+From "A Philosophy of Software Design":
+
+**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+
+**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+
+**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+
+**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+
+## Anti-Patterns
+
+- Don't let sub-agents produce similar designs — enforce radical difference
+- Don't skip comparison — the value is in contrast
+- Don't implement — this is purely about interface shape
+- Don't evaluate based on implementation effort

package/.pi/skills/develop-tdd/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: develop-tdd
+description: "Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md)."
+---
+
+
+# Develop TDD
+
+> **HARD GATE** — Do NOT proceed if on `main` or `master`. Run `kickoff-branch` first to create a feature branch or worktree.
+>
+> **HARD GATE** — Do NOT write code before you have a plan. New feature: `plan-work` → epic capsule tasks. Bug: `investigate-bug` → `specs/bugs/BUG-*.md` (or use `fix-bug` orchestrator).
+>
+> **RECURSIVE DISCIPLINE** — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
+
+## Philosophy
+
+Tests verify behavior through public interfaces, not implementation details. A good test reads like a specification. See [REFERENCE.md](REFERENCE.md) for the horizontal-slice anti-pattern and TDD phase detail.
+
+## Red Flags
+
+If you catch yourself thinking these, stop and reconsider — you are likely deviating from production-grade craft.
+
+| Red Flag | Reality |
+| :--- | :--- |
+| "This is too simple to need tests." | Simple code is where bugs hide. If it's simple, the test is cheap. |
+| "I'll refactor this later." | "Later" is when technical debt becomes bankruptcy. Refactor while Green. |
+| "The tests are already comprehensive." | If you're adding behavior, you need a new test. Coverage ≠ Correctness. |
+| "I'm just fixing a small bug." | Small bugs often indicate deep interface flaws. Investigate root cause. |
+| "I need to mock this internal class." | Mocking internals couples tests to implementation. Mock only I/O. |
+| "This refactor is out of scope." | Leave the code cleaner than you found it (Boy Scout Rule). |
+
+## Workflow
+
+### 1. Planning
+
+- [ ] Read active `specs/epics/*/epic.yaml` story tasks or `specs/bugs/BUG-*.md` — understand verify steps
+- [ ] Confirm interface changes and behaviors to test (prioritize)
+- [ ] Design interfaces for testability — identify [deep modules](deep-modules.md) opportunities
+- [ ] Get user approval on the plan
+
+Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Self-Validating, Timely.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:    Write test for first behavior → test fails → commit: test(<scope>): ...
+GREEN:  Write minimal code to pass → test passes → commit: feat(<scope>): ...
+REFACTOR (optional): clean up → commit: refactor(<scope>): ...
+```
+
+### 3. Incremental Loop
+
+> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent.
+
+For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase.
+
+### 4. Visual Slices (UI alternate workflow)
+
+For UI components where behavioral unit testing is brittle: extract logic into a Controller/ViewModel/Hook (pure TDD), then use Visual Slices for the View layer. See [REFERENCE.md](REFERENCE.md) for the full Visual Slices procedure.
+
+### 5. Refactor
+
+After all tests pass: extract duplication, deepen modules, apply SOLID principles. **Never refactor while RED.**
+
+### 6. Verify
+
+After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
+
+### 7. Manual Verification Handover
+
+Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] No test is ignored without an explicit ambiguity note (T4)
+[ ] Boundary conditions tested: empty, max, min, off-by-one (T5)
+[ ] Tests verify behavior through public interface only — no private methods (T8)
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+[ ] Every new abstraction has an explicit "Reason for Depth" justification
+[ ] Progress committed (Conventional Commits)
+[ ] verify: command passes
+```
+
+## Handoff
+
+Gate: READY -> next: verify-work
+Writes: state.yaml handoff.next_skill = verify-work
+
+---
+
+# Develop TDD — Reference
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things rather than user-facing behavior
+- Tests become insensitive to real changes
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+> The Red Flags table lives in [SKILL.md](SKILL.md#red-flags) — it is core behavioral guidance, not reference detail.
+
+## TDD Phases (Detail)
+
+### Red Phase
+
+Write a failing test first:
+- Test describes the desired observable behavior through the public interface
+- Run the test to confirm it fails for the right reason (not a syntax error, not a typo)
+- Commit: `git commit -m "test(<scope>): <description>"`
+
+### Green Phase
+
+Write the minimum code to make the test pass:
+- No extra logic, no anticipated future cases, no premature optimization
+- Focus only on making the current test pass
+- Commit: `git commit -m "feat(<scope>): <description>"` or `"fix(<scope>): <description>"`
+
+### Refactor Phase
+
+Improve structure without changing behavior:
+- Extract duplication, apply SOLID principles where natural, deepen modules
+- Run tests after each refactor step to ensure behavior is preserved
+- Commit: `git commit -m "refactor(<scope>): <description>"`
+- Apply the Boy Scout Rule: leave the code cleaner than you found it
+
+## Visual Slices (UI Alternate Workflow)
+
+For UI components (SwiftUI, React, Flutter) where behavioral unit testing is brittle or low-signal:
+
+1. **Test-First Logic**: Extract logic (state transitions, formatting, validation) into a Controller, ViewModel, or Hook. This logic MUST follow pure TDD.
+2. **Visual Verification**: For the View/Component itself:
+   - **RED**: Write the component signature and a basic preview/snapshot that fails (or displays placeholder).
+   - **GREEN**: Implement the UI and verify visually via manual run, preview, or snapshot test.
+   - **REFINE**: Adjust styling and layout until it matches the design.
+3. **COMMIT**: `git commit -m "feat(ui): <component name> visual slice verified"`
+
+---
+
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+---
+
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup
+
+---
+
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer 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
+
+---
+
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic
+
+---
+
+# 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");
+});
+```
+
+## Clean Test Heuristics (Uncle Bob, Ch 17)
+
+Apply these specific heuristics to maintain a high-quality suite:
+
+- **T1: Insufficient Tests**: A test suite should test everything that could possibly break. Don't stop at "it seems to work."
+- **T4: Ignored Tests**: Never ignore a test without documenting the ambiguity. An ignored test is a silent warning of a gap in understanding.
+- **T5: Test Boundary Conditions**: Most bugs happen at the edges. Test the exact boundaries (e.g., empty strings, max integers, off-by-one indices).
+- **T6: Exhaustively Test Near Bugs**: Bugs congregate. If you find one, there are likely others nearby; test that area thoroughly.
+- **T9: Tests Should Be Fast**: Slow tests don't get run. Keep them fast so they remain part of the core developer loop.