Test Writer

Write strict, executable proof for every non-documentation change. A change is not done until a hard test fails for the broken behavior and passes for the fixed behavior.

Core Rule

Every code, config, dependency, migration, build, script, UI, API, and test change must have a hard executable test or verification that proves the changed effect through the system's public API, UI, command, data store, generated output, or observable side effect.

Use search tools to find context, never as proof. A test that reads source files and checks for text such as function names, strings, branches, imports, or config keys is not a hard test.

Strict Gate

Before claiming the work is complete, all boxes must be true:

• Every non-documentation change has a matching hard test or executable verification.
• Each new or changed behavior test was observed failing before implementation.
• Each test failed for the intended reason, not because of a typo, missing import, broken fixture, or bad setup.
• Each hard test passes after implementation.
• Each hard test was proven sensitive by a sabotage check: temporarily break the implementation, fixture, route, config, or assertion target, confirm the test fails, then restore it.
• The final report names the test file, RED command/result, GREEN command/result, and sabotage command/result.

If any box is missing, the work is not verified. Do not describe it as done.

Workflow

1. Inventory the change.
   • List every changed non-documentation file and the behavior, command, config effect, generated output, or contract it can affect.
   • For each item, choose the smallest hard test that would fail if that item were wrong.
2. Write the failing test first.
   • Use the repo's existing test framework and nearest test style.
   • Exercise real code. Mock only at external boundaries such as network, time, payment providers, or filesystem when unavoidable.
   • Run the smallest relevant test command and confirm it fails for the expected reason.
3. Implement the change.
   • Write only enough code to make the new test pass.
   • Keep existing tests green.
4. Prove the test is hard to fool.
   • The test must fail if the new branch is removed, the predicate is inverted, validation is disabled, persistence is skipped, or the handler is not wired.
   • Make a temporary local sabotage such as reverting the new condition, returning the old value, disabling the route, undoing the config, or breaking the generated output. Run the test to watch it fail, then restore the implementation.
5. Report the evidence.
   • Name every changed non-documentation file and its matching hard test.
   • Include the RED failure command/result.
   • Include the GREEN passing command/result.
   • Include the sabotage failure command/result.

What Counts

Exceptions

Exceptions are rare and must be explicit.

Allowed no-test exceptions:

• Documentation-only, comments-only, or formatting-only changes that cannot affect runtime, generated output, configuration, packaging, or behavior.
• A blocked environment where dependencies, credentials, services, or platform access make execution impossible.

Blocked execution is not success. Report it as Blocked, include the exact command attempted and failure, and do not claim the change is verified.

Forbidden Proof

Do not count these as the required test:

• grep, rg, awk, or source-text assertions that only prove code exists.
• Snapshot-only tests with no behavioral assertion.
• Import-only tests that only prove a module loads.
• Tests that assert mocks were called while the real behavior is untested.
• Typecheck, lint, build, or coverage numbers as the only proof.
• Manual smoke checks as the only proof.

These checks can supplement the real test, but they cannot replace it.

Rationalizations

Example

test("rejects duplicate slugs after normalization", async () => {
  const projects = createProjectStore();

  await projects.create({ slug: "Alpha" });

  await expect(projects.create({ slug: " alpha " })).rejects.toThrow(
    "slug already exists",
  );
});

This fails if trimming, case normalization, duplicate detection, or error propagation is missing.

test("normalizes slugs", () => {
  const source = readFileSync("src/project-store.ts", "utf8");
  expect(source).toContain("trim().toLowerCase()");
});

This only proves text exists. The app can still accept duplicate slugs.

Red Flags

• The new test passed on the first run.
• The test would still pass if the implementation returned the old value.
• The assertion checks implementation text instead of observable behavior.
• The test only checks that a helper was called.
• The test name says "works" but not what behavior works.
• The change touches any non-documentation file and the final report has no RED and sabotage failure.
• The final answer says "verified" while any hard test, RED run, GREEN run, or sabotage run is missing.

Any red flag means the work is not verified. Tighten the test until it catches broken behavior.