Skip to content

Kartik-Doye/Ravengard-AI-Recruiter / .agents/skills/proof

Chooses and implements the cheapest trustworthy test boundary for a behavior or invariant, including regression, property, contract, integration, and end-to-end tests. Use when adding tests, protecting a bug fix, or proving changed behavior without optimizing for coverage counts.

FileKindSize
SKILL.mdskill md9.6 KB
references/boundary-picker.mdmarkdown3.8 KB
references/research.mdmarkdown2.3 KB

references/boundary-picker.md

View on GitHub
# Boundary picker: which layer, and why

## The layers

| Layer | Tests through | Catches | Costs |
| --- | --- | --- | --- |
| Unit | one function/class in isolation | logic errors, edge cases | pennies: write freely |
| Component | one UI component rendered | rendering, props, interaction | cheap-moderate |
| Integration | several real modules together | wiring mistakes, wrong assumptions between units | moderate |
| Contract | consumer ↔ provider agreement | breaking API/schema changes | moderate |
| API | real HTTP against the app | the actual contract: status, shape, auth | moderate: the workhorse |
| Database | real migrations/queries vs real engine | SQL truth: constraints, transactions, locks | needs infra discipline |
| End-to-end | the whole running app, UI included | only-the-user-would-notice breaks | expensive, flaky-prone: budget tightly |
| Browser | real user flows | console errors, network failures, visual reality | most expensive: see roadtest |

## Decision table

| The behavior lives in… | Test at |
| --- | --- |
| Pure logic (parsing, calculation, state machines) | unit |
| Business rule that touches the DB | integration or database (real engine, not mocked) |
| An HTTP endpoint's contract | API level: status codes, shapes, auth, errors |
| Schema changes / migrations | database: up **and** down, against the real engine |
| Provider/consumer agreements (client libs, webhooks) | contract |
| A user flow across pages | end-to-end: only for the few money paths |
| Anything visual/console/network | browser (roadtest owns that evidence) |

## The workhorse default

**API-level tests against a running app** catch the most real regressions
per unit of pain: they exercise routing, validation, auth, business
logic and serialization together, without browser flakiness. When in
doubt, start there and push down (unit) for logic corners, up (e2e) only
for critical paths.

## Flaky-test diagnosis (before quarantining)

Flakiness is a signal, not weather. In order of likelihood: shared state
between tests (DB rows, singletons, temp dirs) → timing/sleep
assertions (replace with condition-waiting) → concurrency in the code
under test (the flake is a real race, file a bug) → unordered data
(hash order, map iteration) → external dependency variability (freeze
with fixtures). Only external-flakiness gets the quarantine marker; the
rest gets fixed: a race you keep retrying past is a production incident
in waiting.

## Property-based tests (when they earn their place)

Use when a behavior has an invariant over a space of inputs: encoders
round-trip, parsers accept-then-serialize, invariants hold under
arbitrary operation sequences. One property with a generator beats 20
hand-picked examples for exactly that behavior; everywhere else they
add framework weight. (fast-check, hypothesis, proptest per stack.)

## Anti-patterns

1. **Mock theatre**: six mocks arranged so the test asserts its own
   setup. If deleting the feature keeps the test green, the test is
   decoration.
2. **Implementation-coupled assertions**: asserting `getUser()` was
   called twice instead of asserting the user sees their name.
3. **The 70% hero suite**: e2e tests for everything; suite takes 40
   minutes; everyone runs it "later". Few e2e, many API, plenty unit.
4. **Snapshot as thought**: a giant snapshot nobody reviews just hides
   regressions until the day someone blindly updates it.
5. **Flake tolerance**: retry-until-green masks real races. Fix or
   quarantine with an issue, visibly.
6. **Coverage theater**: chasing a coverage percentage with trivial
   tests. Coverage numbers describe the suite; they are not the goal.
7. **Vacuous AI Tests**: tests generated by an LLM that pass vacuously (e.g., `assert True`, or mocking the system under test). Use **Mutation Validation** (deliberately breaking the code to ensure the test fails) to expose them.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall