@tamsensedev/runner 0.10.0 → 0.18.0

package/library/skills/task-interview/SKILL.md

@@ -1,84 +1,84 @@
----
-name: task-interview
-description: Use when a task or spec leaves a decision open and you are tempted to ask: research first, ask only questions that pass three tests, settle corner cases as assumptions with a reason, and either ask in short rounds with a recommended answer first (when a person can answer, or on the TAMsense spec step with submit_questions) or decide with the recommendation and report it (on any other unattended TAMsense step).
----
-
-# Task interview
-
-Finding facts is your job. Decisions about intent belong to the person who owns the task. Most "questions" are facts you have not looked up yet, or corners with a safe default. Ask only what is left after both.
-
-## 1. Research before any question
-
-Look before you ask: the task, the spec and its decisions, the project's rules (`project-orientation`), the code around the change, existing tests, data you can read locally.
-
-- Never ask where something is, which component to use or how the code works today. Look it up.
-- If the answer has several plausible candidates in the code, the question becomes "which of these", with the real paths as options.
-- When a person corrects a fact, check it in the code before you rely on it.
-
-## 2. Sweep the corners instead of asking about them
-
-Most defects are corners: one part of the change meeting one unusual condition. More questions do not find them; a sweep does. For each part of the change, go through:
-
-- empty or missing data, one item, very many items;
-- invalid or too long input, first use and repeated use;
-- missing access, a signed-out user, two people editing at once;
-- a failed or slow external call, old stored data, existing users;
-- phone width; numbers and money (zero, rounding, unknown versus zero); dates and time zones.
-
-Settle every condition that applies in one of three ways: an assumption with its reason (a safe default exists), out of scope, or a question (only if it passes the test below).
-
-## 3. The question test
-
-Ask a question only if all three hold:
-
-1. **Not discoverable.** The code, the data, the spec and the project's rules do not answer it.
-2. **It changes the result.** The two most likely answers lead to different changes or different acceptance criteria.
-3. **No safe default.** Or a wrong default is costly: lost or wrong data, money, permissions and privacy, a public API or stored format, a migration that is hard to undo, or visible text and behaviour the owner cares about.
-
-Rank the questions that pass by impact times uncertainty. On a tie: scope first, then data and security, then what the user sees, then technical details. Stop when you can predict the answer to the next questions; record those as assumptions.
-
-## 4. How to write a question
-
-```
-id: empty_state
-Question: What should the task list show when a board has no tasks?
-Why it matters: It decides the empty-state text and whether a "Create a task" button is added.
-Options:
-  1. A short hint (recommended): the page says "No tasks yet", nothing else changes.
-  2. A hint and a button: the page also offers "Create a task", which needs a new route.
-```
-
-- One plain sentence; the owner may not be a developer.
-- A "why it matters" line.
-- 2 to 4 mutually exclusive options, the recommended one first and marked; each option says what happens if it is chosen.
-- Several picks only when the options are additive.
-- Zero questions is a good result.
-
-## 5. Rounds
-
-- **Round 1:** at most 4 questions, ideally 2 or 3. Ask only questions that do not depend on another open question of the same round; note dependent decisions for later.
-- **Round 2 (optional):** at most 3 more, only if an answer was vague ("not sure", "depends"), contradicts another answer or the code, or unlocked a dependent decision.
-- No third round. About 6 questions in total. Whatever is left becomes an assumption.
-- An unanswered question takes the recommended option and is recorded as an assumption.
-
-## 6. When nobody can answer (a TAMsense run)
-
-On the TAMsense spec step the owner answers after the run: hand the brief and the round's questions in with `submit_questions` and finish. The owner clicks through them on the task page, and the next round or the spec continues from your brief.
-
-On any other step of a TAMsense run nobody answers, so never stop to wait:
-
-1. Take the recommended option and keep working.
-2. If a wrong guess would be costly and hard to undo (deleting data, a destructive migration, money, permissions), build the safe part only and leave the risky part out.
-3. In the report, list each decision as the question, the options, what you chose and why, so the owner can correct it in one reply. If the board lets you hand the task back to the spec step and the open decision blocks the work, hand it back with these questions in the note.
-
-## Common mistakes
-
-| Thought | What to do instead |
-|---|---|
-| "I'll ask which file handles this" | Search the code; ask only to choose between real candidates. |
-| "Better ask about the empty state too" | If a safe default exists, write it as an assumption with the reason. |
-| "Let me ask everything at once" | One round of independent questions; dependent ones wait. |
-| "Whatever you think is best" came back | That is a delegation: take your recommendation and say so. |
-| "I'll wait for an answer" | In a run nobody answers: decide, record, report. |
-
-Sources: adapted from openai/codex Plan Mode template and request_user_input tool (Apache-2.0, commit 430a167), github/spec-kit clarify and specify commands (MIT, commit c06e670), mattpocock/skills grilling (MIT, commit 5beb35b), awslabs/aidlc-workflows corner checklist and requirements analysis (MIT-0, commit 95d2b44), addyosmani/agent-skills interview-me (MIT, commit aeac41d) and humanlayer/humanlayer create_plan (Apache-2.0, commit 99abe67). Changed: merged into one question policy, rewritten for batched rounds and unattended runs.
+---
+name: task-interview
+description: Use when a task or spec leaves a decision open and you are tempted to ask: research first, ask only questions that pass three tests, settle corner cases as assumptions with a reason, and either ask in short rounds with a recommended answer first (when a person can answer, or on the TAMsense spec step with submit_questions) or decide with the recommendation and report it (on any other unattended TAMsense step).
+---
+
+# Task interview
+
+Finding facts is your job. Decisions about intent belong to the person who owns the task. Most "questions" are facts you have not looked up yet, or corners with a safe default. Ask only what is left after both.
+
+## 1. Research before any question
+
+Look before you ask: the task, the spec and its decisions, the project's rules (`project-orientation`), the code around the change, existing tests, data you can read locally.
+
+- Never ask where something is, which component to use or how the code works today. Look it up.
+- If the answer has several plausible candidates in the code, the question becomes "which of these", with the real paths as options.
+- When a person corrects a fact, check it in the code before you rely on it.
+
+## 2. Sweep the corners instead of asking about them
+
+Most defects are corners: one part of the change meeting one unusual condition. More questions do not find them; a sweep does. For each part of the change, go through:
+
+- empty or missing data, one item, very many items;
+- invalid or too long input, first use and repeated use;
+- missing access, a signed-out user, two people editing at once;
+- a failed or slow external call, old stored data, existing users;
+- phone width; numbers and money (zero, rounding, unknown versus zero); dates and time zones.
+
+Settle every condition that applies in one of three ways: an assumption with its reason (a safe default exists), out of scope, or a question (only if it passes the test below).
+
+## 3. The question test
+
+Ask a question only if all three hold:
+
+1. **Not discoverable.** The code, the data, the spec and the project's rules do not answer it.
+2. **It changes the result.** The two most likely answers lead to different changes or different acceptance criteria.
+3. **No safe default.** Or a wrong default is costly: lost or wrong data, money, permissions and privacy, a public API or stored format, a migration that is hard to undo, or visible text and behaviour the owner cares about.
+
+Rank the questions that pass by impact times uncertainty. On a tie: scope first, then data and security, then what the user sees, then technical details. Stop when you can predict the answer to the next questions; record those as assumptions.
+
+## 4. How to write a question
+
+```
+id: empty_state
+Question: What should the task list show when a board has no tasks?
+Why it matters: It decides the empty-state text and whether a "Create a task" button is added.
+Options:
+  1. A short hint (recommended): the page says "No tasks yet", nothing else changes.
+  2. A hint and a button: the page also offers "Create a task", which needs a new route.
+```
+
+- One plain sentence; the owner may not be a developer.
+- A "why it matters" line.
+- 2 to 4 mutually exclusive options, the recommended one first and marked; each option says what happens if it is chosen.
+- Several picks only when the options are additive.
+- Zero questions is a good result.
+
+## 5. Rounds
+
+- **Round 1:** at most 4 questions, ideally 2 or 3. Ask only questions that do not depend on another open question of the same round; note dependent decisions for later.
+- **Round 2 (optional):** at most 3 more, only if an answer was vague ("not sure", "depends"), contradicts another answer or the code, or unlocked a dependent decision.
+- No third round. About 6 questions in total. Whatever is left becomes an assumption.
+- An unanswered question takes the recommended option and is recorded as an assumption.
+
+## 6. When nobody can answer (a TAMsense run)
+
+On the TAMsense spec step the owner answers after the run: hand the brief and the round's questions in with `submit_questions` and finish. The owner clicks through them on the task page, and the next round or the spec continues from your brief.
+
+On any other step of a TAMsense run nobody answers, so never stop to wait:
+
+1. Take the recommended option and keep working.
+2. If a wrong guess would be costly and hard to undo (deleting data, a destructive migration, money, permissions), build the safe part only and leave the risky part out.
+3. In the report, list each decision as the question, the options, what you chose and why, so the owner can correct it in one reply. If the board lets you hand the task back to the spec step and the open decision blocks the work, hand it back with these questions in the note.
+
+## Common mistakes
+
+| Thought | What to do instead |
+|---|---|
+| "I'll ask which file handles this" | Search the code; ask only to choose between real candidates. |
+| "Better ask about the empty state too" | If a safe default exists, write it as an assumption with the reason. |
+| "Let me ask everything at once" | One round of independent questions; dependent ones wait. |
+| "Whatever you think is best" came back | That is a delegation: take your recommendation and say so. |
+| "I'll wait for an answer" | In a run nobody answers: decide, record, report. |
+
+Sources: adapted from openai/codex Plan Mode template and request_user_input tool (Apache-2.0, commit 430a167), github/spec-kit clarify and specify commands (MIT, commit c06e670), mattpocock/skills grilling (MIT, commit 5beb35b), awslabs/aidlc-workflows corner checklist and requirements analysis (MIT-0, commit 95d2b44), addyosmani/agent-skills interview-me (MIT, commit aeac41d) and humanlayer/humanlayer create_plan (Apache-2.0, commit 99abe67). Changed: merged into one question policy, rewritten for batched rounds and unattended runs.

package/library/skills/test-driven-development/SKILL.md

@@ -1,116 +1,116 @@
----
-name: test-driven-development
-description: Use when adding behaviour or fixing a bug in a project, before writing the implementation: write a test in the project's own framework, watch it fail for the right reason, make it pass with minimal code, then run the suite. Covers what to do when the project has no test setup.
----
-
-# Test-driven development
-
-If you never saw a test fail, you do not know that it tests anything. Write the test first, watch it fail, then write the code.
-
-## Step 0: Find the project's test setup
-
-Before anything else (see `project-orientation`):
-
-- Which framework, where tests live, how they are named, which helpers and fixtures exist, and the exact command to run one file and the whole suite.
-- Copy the shape of a neighbouring test: imports, setup, naming, assertion style.
-
-**If the project has no test setup at all:** do not add a test framework, new dependencies or a test folder structure the maintainers did not choose. Verify the change another way that you can show evidence for (type check, build, running the code with a fixture input, a throwaway script outside the repository) and write in the report: "No test setup in this repository; verified by: ...".
-
-**If tests exist but not for this area:** add the test in the existing framework, next to the code, following the closest existing example.
-
-## When to use it, and when not
-
-Use it for new behaviour, bug fixes, and behaviour changes in code that has a reasonable seam to test at.
-
-Usually skip it, and say so in the report, for: configuration-only changes, generated code, pure markup or styling with no logic, copy changes, dependency bumps, and code with no seam that can show the behaviour (then explain the gap rather than writing a hollow test). Exploratory spikes are fine, but throw the spike away or start the test-first cycle from it before you commit.
-
-## The cycle
-
-### Red: write one failing test
-
-One behaviour per test, a name that reads as a sentence about it, real code rather than mocks where that is cheap.
-
-```ts
-test('retries a failing call up to 3 times, then succeeds', async () => {
-  let attempts = 0
-  const call = async () => {
-    attempts++
-    if (attempts < 3) throw new Error('fail')
-    return 'ok'
-  }
-
-  await expect(retry(call)).resolves.toBe('ok')
-  expect(attempts).toBe(3)
-})
-```
-
-Before writing the body, name the production change that would make this test fail. If you cannot name one, the test is not testing behaviour. More in [references/writing-good-tests.md](references/writing-good-tests.md).
-
-### Verify red: run it and read the failure
-
-```
-pnpm vitest run src/retry.test.ts
-```
-
-- It must **fail**, not error. A typo, a missing import or a syntax error is not a red test.
-- The failure message must be the one you expect ("expected 'ok', received undefined").
-- It must fail because the behaviour is missing, not because of setup.
-- If it passes immediately, it tests existing behaviour or nothing at all: fix the test.
-
-### Green: the minimal code that passes
-
-Write the simplest code that makes this test pass. No extra options, no handling for cases no test asks for yet. Do not change the test to fit the code.
-
-### Verify green
-
-Run the test again, then the tests around it, then the project's full suite (or the widest suite that runs in reasonable time). A green file is not a green suite. Output should be clean: no new warnings or errors in the log.
-
-Any failure in the wider run goes in the report by name, including ones you did not cause (check against the baseline from `project-orientation`).
-
-### Refactor
-
-Only on green: remove duplication, improve names, extract helpers. Re-run after each change. Do not add behaviour while refactoring.
-
-Repeat for the next behaviour: one test, one minimal implementation, at a time. Do not write the whole test file first.
-
-## If you wrote the code first
-
-It happens: an exploration turned into the fix, or the change was made before this skill was loaded. Do not pretend. Prove the test can fail:
-
-1. Save your change to the production file: `git diff -- path/to/file > "$TMPDIR/fix.patch"` (any temp location outside the repository).
-2. Restore the original: `git checkout -- path/to/file`.
-3. Run the new test and confirm it fails for the right reason.
-4. Re-apply: `git apply "$TMPDIR/fix.patch"`, check with `git diff --stat` that the change is back, and run the test again to see it pass.
-
-If the test passes without your change, it does not cover the change. Fix the test.
-
-## Bug fixes
-
-1. Write a test that reproduces the reported bug exactly (the input, the wrong output). For a hard bug, follow `systematic-debugging` first.
-2. Watch it fail with the symptom from the report.
-3. Fix the cause. Watch it pass.
-4. Run the suite.
-
-## Keep tests deterministic
-
-Fixed dates and time zones, seeded random data, no dependence on test order, no real network, temp folders per test. Wait for conditions, not for time (see `systematic-debugging`, flaky tests reference).
-
-## Common rationalisations
-
-| Excuse | Reality |
-|---|---|
-| "Too simple to test" | Simple code breaks too; the test takes a minute. |
-| "I'll add tests after" | Tests written after pass immediately and prove nothing; they check what you built, not what was asked. |
-| "I already tried it by hand" | A manual try leaves no record and is not repeated on the next change. |
-| "The existing code has no tests" | Add tests for the part you change, in the project's framework. |
-| "Hard to test" | Often a sign the design is hard to use. Find a better seam, or report the gap. |
-| "I need to mock everything" | The code is too coupled, or the test is at the wrong level. Test higher up with real collaborators. |
-
-## Done when
-
-- [ ] Each new behaviour and each fixed bug has a test that you saw fail for the right reason, then pass.
-- [ ] Tests assert real behaviour through the public surface, with expected values written out by hand.
-- [ ] The full relevant suite passes, or failures are listed with their cause (yours fixed, pre-existing reported).
-- [ ] The report says which tests were added, or why none were (no test setup, no seam, not applicable).
-
-Sources: obra/superpowers (MIT, commit bb92a77) test-driven-development. Changed: rewritten for unattended work in existing repositories.
+---
+name: test-driven-development
+description: Use when adding behaviour or fixing a bug in a project, before writing the implementation: write a test in the project's own framework, watch it fail for the right reason, make it pass with minimal code, then run the suite. Covers what to do when the project has no test setup.
+---
+
+# Test-driven development
+
+If you never saw a test fail, you do not know that it tests anything. Write the test first, watch it fail, then write the code.
+
+## Step 0: Find the project's test setup
+
+Before anything else (see `project-orientation`):
+
+- Which framework, where tests live, how they are named, which helpers and fixtures exist, and the exact command to run one file and the whole suite.
+- Copy the shape of a neighbouring test: imports, setup, naming, assertion style.
+
+**If the project has no test setup at all:** do not add a test framework, new dependencies or a test folder structure the maintainers did not choose. Verify the change another way that you can show evidence for (type check, build, running the code with a fixture input, a throwaway script outside the repository) and write in the report: "No test setup in this repository; verified by: ...".
+
+**If tests exist but not for this area:** add the test in the existing framework, next to the code, following the closest existing example.
+
+## When to use it, and when not
+
+Use it for new behaviour, bug fixes, and behaviour changes in code that has a reasonable seam to test at.
+
+Usually skip it, and say so in the report, for: configuration-only changes, generated code, pure markup or styling with no logic, copy changes, dependency bumps, and code with no seam that can show the behaviour (then explain the gap rather than writing a hollow test). Exploratory spikes are fine, but throw the spike away or start the test-first cycle from it before you commit.
+
+## The cycle
+
+### Red: write one failing test
+
+One behaviour per test, a name that reads as a sentence about it, real code rather than mocks where that is cheap.
+
+```ts
+test('retries a failing call up to 3 times, then succeeds', async () => {
+  let attempts = 0
+  const call = async () => {
+    attempts++
+    if (attempts < 3) throw new Error('fail')
+    return 'ok'
+  }
+
+  await expect(retry(call)).resolves.toBe('ok')
+  expect(attempts).toBe(3)
+})
+```
+
+Before writing the body, name the production change that would make this test fail. If you cannot name one, the test is not testing behaviour. More in [references/writing-good-tests.md](references/writing-good-tests.md).
+
+### Verify red: run it and read the failure
+
+```
+pnpm vitest run src/retry.test.ts
+```
+
+- It must **fail**, not error. A typo, a missing import or a syntax error is not a red test.
+- The failure message must be the one you expect ("expected 'ok', received undefined").
+- It must fail because the behaviour is missing, not because of setup.
+- If it passes immediately, it tests existing behaviour or nothing at all: fix the test.
+
+### Green: the minimal code that passes
+
+Write the simplest code that makes this test pass. No extra options, no handling for cases no test asks for yet. Do not change the test to fit the code.
+
+### Verify green
+
+Run the test again, then the tests around it, then the project's full suite (or the widest suite that runs in reasonable time). A green file is not a green suite. Output should be clean: no new warnings or errors in the log.
+
+Any failure in the wider run goes in the report by name, including ones you did not cause (check against the baseline from `project-orientation`).
+
+### Refactor
+
+Only on green: remove duplication, improve names, extract helpers. Re-run after each change. Do not add behaviour while refactoring.
+
+Repeat for the next behaviour: one test, one minimal implementation, at a time. Do not write the whole test file first.
+
+## If you wrote the code first
+
+It happens: an exploration turned into the fix, or the change was made before this skill was loaded. Do not pretend. Prove the test can fail:
+
+1. Save your change to the production file: `git diff -- path/to/file > "$TMPDIR/fix.patch"` (any temp location outside the repository).
+2. Restore the original: `git checkout -- path/to/file`.
+3. Run the new test and confirm it fails for the right reason.
+4. Re-apply: `git apply "$TMPDIR/fix.patch"`, check with `git diff --stat` that the change is back, and run the test again to see it pass.
+
+If the test passes without your change, it does not cover the change. Fix the test.
+
+## Bug fixes
+
+1. Write a test that reproduces the reported bug exactly (the input, the wrong output). For a hard bug, follow `systematic-debugging` first.
+2. Watch it fail with the symptom from the report.
+3. Fix the cause. Watch it pass.
+4. Run the suite.
+
+## Keep tests deterministic
+
+Fixed dates and time zones, seeded random data, no dependence on test order, no real network, temp folders per test. Wait for conditions, not for time (see `systematic-debugging`, flaky tests reference).
+
+## Common rationalisations
+
+| Excuse | Reality |
+|---|---|
+| "Too simple to test" | Simple code breaks too; the test takes a minute. |
+| "I'll add tests after" | Tests written after pass immediately and prove nothing; they check what you built, not what was asked. |
+| "I already tried it by hand" | A manual try leaves no record and is not repeated on the next change. |
+| "The existing code has no tests" | Add tests for the part you change, in the project's framework. |
+| "Hard to test" | Often a sign the design is hard to use. Find a better seam, or report the gap. |
+| "I need to mock everything" | The code is too coupled, or the test is at the wrong level. Test higher up with real collaborators. |
+
+## Done when
+
+- [ ] Each new behaviour and each fixed bug has a test that you saw fail for the right reason, then pass.
+- [ ] Tests assert real behaviour through the public surface, with expected values written out by hand.
+- [ ] The full relevant suite passes, or failures are listed with their cause (yours fixed, pre-existing reported).
+- [ ] The report says which tests were added, or why none were (no test setup, no seam, not applicable).
+
+Sources: obra/superpowers (MIT, commit bb92a77) test-driven-development. Changed: rewritten for unattended work in existing repositories.

package/library/skills/test-driven-development/references/writing-good-tests.md

@@ -1,85 +1,85 @@
-# Writing good tests
-
-Read this when writing or changing a test, adding a mock, or adding a test helper.
-
-A test exists to catch a specific break. Two rules carry most of the weight:
-
-1. Every test names the break it catches.
-2. Every test exercises the real thing.
-
-## Rule 1: name the break
-
-Before writing the body, answer: which production change would make this test fail, and is that change a bug or a deliberate decision? A good test catches a wrong branch, a missing side effect, a wrong argument, a boundary case or a broken contract.
-
-**Derive expected values independently.** Use literals and hand-checked fixtures. An expected value computed by the code under test (or its helpers) passes whatever the code does.
-
-```ts
-// Bad: the same builder produces both sides, so it is always equal
-const expected = buildSearchQuery({ tag: 'urgent' })
-expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected)
-
-// Bad: recomputes the answer the way the code does
-expect(add(a, b)).toBe(a + b)
-
-// Good: written out by hand
-expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"')
-```
-
-Table-driven tests with literal expected values are a good shape for many cases.
-
-**No change detectors.** A test that only fails on intentional decisions (a constant's value, exact message wording, private structure) fires on every redesign and sleeps through real bugs. Test the behaviour that depends on the decision: not `expect(MAX_RETRIES).toBe(5)` but "a failing call is retried 5 times and a sixth attempt never happens".
-
-**Behaviour, not source text.** Asserting that a file contains a certain line proves only that the file is the file. Run the script, config or template against a controlled input and check the output, side effect or exit code.
-
-**Your code, not the framework.** Test the contract your code makes at its boundary: the route you register, the query you build, the payload you send. Do not test that the router calls a registered handler; that is the framework's job. Constructors, getters and simple pass-throughs earn a test only when they validate, normalise, default, derive or cause a side effect.
-
-**Through the public surface.** Test via the function, endpoint, component or command that callers use. A test that breaks when you refactor internals without changing behaviour is coupled to implementation. Avoid checking results through a side channel (querying the database directly) when the public interface can show them.
-
-## Rule 2: exercise the real thing
-
-**Never assert on a mock.** An assertion that a mock was rendered or exists passes when the mock is there and says nothing about the component.
-
-```ts
-// Bad: tests the mock
-expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument()
-
-// Good: tests the real behaviour
-expect(screen.getByRole('navigation')).toBeInTheDocument()
-```
-
-**Mock at the right level.** Before replacing a method, learn all its side effects. Mock the slow or external part below it (network, paid API, clock, email) and keep what the test depends on real. A mock that swallows a write that the code later reads makes the test pass while the real thing breaks.
-
-**Make doubles specific.** When arguments, call counts or order are part of the contract, assert them. Give success, error and malformed responses their own fixtures, so the wrong branch cannot satisfy the test.
-
-**Mirror real data completely.** Fake responses should have the full structure of the real one, not only the fields this test reads. Partial fakes hide failures in code that reads the other fields.
-
-**Production code carries production methods only.** Cleanup or reset methods that only tests call belong in test utilities, not on the production class.
-
-**Prefer real components over elaborate mocks.** When mock setup is longer than the test logic, or the test breaks whenever the mock changes, switch to a test with real collaborators (an in-memory database, the real module, the project's existing test server).
-
-## The mutation check
-
-Before finishing, imagine small breaks in the production code. At least one test should fail for each realistic one:
-
-- A wrong constant or argument.
-- A wrong branch taken.
-- A missing state change or side effect.
-- An empty or default return value.
-- Missing validation for zero, empty, null, unauthorised or malformed input.
-
-If nothing fails for a realistic mutation, that behaviour is unprotected. For an important change you can make the mutation for real: invert one condition, run the tests, confirm a failure, restore the line, and confirm with `git diff` that it is restored.
-
-## Warning signs
-
-- Setup and assertion share the same object, so they are equal by construction.
-- The test can only fail by crashing or by a missing selector.
-- The test fails on every intentional change but never on accidental breakage.
-- Expected values are hidden behind loops, builders or helpers.
-- The test greps source text.
-- The test exists for coverage and checks no outcome.
-- An assertion checks a `*-mock` test id, or fails if you remove the mock.
-- A method is called only from test files.
-- Mock setup is more than half the test, or you cannot say why the mock is needed.
-- Writing all the tests for a feature before any implementation: tests for imagined behaviour test the shape of things, not what users see. Go one test at a time.
-
-Sources: obra/superpowers (MIT, commit bb92a77) writing-good-tests and mattpocock/skills (MIT, commit 5beb35b) tdd. Changed: shortened and merged.
+# Writing good tests
+
+Read this when writing or changing a test, adding a mock, or adding a test helper.
+
+A test exists to catch a specific break. Two rules carry most of the weight:
+
+1. Every test names the break it catches.
+2. Every test exercises the real thing.
+
+## Rule 1: name the break
+
+Before writing the body, answer: which production change would make this test fail, and is that change a bug or a deliberate decision? A good test catches a wrong branch, a missing side effect, a wrong argument, a boundary case or a broken contract.
+
+**Derive expected values independently.** Use literals and hand-checked fixtures. An expected value computed by the code under test (or its helpers) passes whatever the code does.
+
+```ts
+// Bad: the same builder produces both sides, so it is always equal
+const expected = buildSearchQuery({ tag: 'urgent' })
+expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected)
+
+// Bad: recomputes the answer the way the code does
+expect(add(a, b)).toBe(a + b)
+
+// Good: written out by hand
+expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"')
+```
+
+Table-driven tests with literal expected values are a good shape for many cases.
+
+**No change detectors.** A test that only fails on intentional decisions (a constant's value, exact message wording, private structure) fires on every redesign and sleeps through real bugs. Test the behaviour that depends on the decision: not `expect(MAX_RETRIES).toBe(5)` but "a failing call is retried 5 times and a sixth attempt never happens".
+
+**Behaviour, not source text.** Asserting that a file contains a certain line proves only that the file is the file. Run the script, config or template against a controlled input and check the output, side effect or exit code.
+
+**Your code, not the framework.** Test the contract your code makes at its boundary: the route you register, the query you build, the payload you send. Do not test that the router calls a registered handler; that is the framework's job. Constructors, getters and simple pass-throughs earn a test only when they validate, normalise, default, derive or cause a side effect.
+
+**Through the public surface.** Test via the function, endpoint, component or command that callers use. A test that breaks when you refactor internals without changing behaviour is coupled to implementation. Avoid checking results through a side channel (querying the database directly) when the public interface can show them.
+
+## Rule 2: exercise the real thing
+
+**Never assert on a mock.** An assertion that a mock was rendered or exists passes when the mock is there and says nothing about the component.
+
+```ts
+// Bad: tests the mock
+expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument()
+
+// Good: tests the real behaviour
+expect(screen.getByRole('navigation')).toBeInTheDocument()
+```
+
+**Mock at the right level.** Before replacing a method, learn all its side effects. Mock the slow or external part below it (network, paid API, clock, email) and keep what the test depends on real. A mock that swallows a write that the code later reads makes the test pass while the real thing breaks.
+
+**Make doubles specific.** When arguments, call counts or order are part of the contract, assert them. Give success, error and malformed responses their own fixtures, so the wrong branch cannot satisfy the test.
+
+**Mirror real data completely.** Fake responses should have the full structure of the real one, not only the fields this test reads. Partial fakes hide failures in code that reads the other fields.
+
+**Production code carries production methods only.** Cleanup or reset methods that only tests call belong in test utilities, not on the production class.
+
+**Prefer real components over elaborate mocks.** When mock setup is longer than the test logic, or the test breaks whenever the mock changes, switch to a test with real collaborators (an in-memory database, the real module, the project's existing test server).
+
+## The mutation check
+
+Before finishing, imagine small breaks in the production code. At least one test should fail for each realistic one:
+
+- A wrong constant or argument.
+- A wrong branch taken.
+- A missing state change or side effect.
+- An empty or default return value.
+- Missing validation for zero, empty, null, unauthorised or malformed input.
+
+If nothing fails for a realistic mutation, that behaviour is unprotected. For an important change you can make the mutation for real: invert one condition, run the tests, confirm a failure, restore the line, and confirm with `git diff` that it is restored.
+
+## Warning signs
+
+- Setup and assertion share the same object, so they are equal by construction.
+- The test can only fail by crashing or by a missing selector.
+- The test fails on every intentional change but never on accidental breakage.
+- Expected values are hidden behind loops, builders or helpers.
+- The test greps source text.
+- The test exists for coverage and checks no outcome.
+- An assertion checks a `*-mock` test id, or fails if you remove the mock.
+- A method is called only from test files.
+- Mock setup is more than half the test, or you cannot say why the mock is needed.
+- Writing all the tests for a feature before any implementation: tests for imagined behaviour test the shape of things, not what users see. Go one test at a time.
+
+Sources: obra/superpowers (MIT, commit bb92a77) writing-good-tests and mattpocock/skills (MIT, commit 5beb35b) tdd. Changed: shortened and merged.