litmus CLAUDE.md

litmus — how to respond to it

litmus is a test-planning guardrail. When it speaks, it is reminding you not to finish a change without deciding how it gets tested.

When a litmus reminder appears

• Advisory message (🧪 litmus …): a non-blocking nudge. Consider the suggested test types. If the change genuinely needs no tests, say why in one line and move on. Don't ignore it silently.
• Block reason (STOP — litmus (block mode) …): the turn is held. Do exactly what it says, in two steps:
  1. Triage into one markdown table (test type · needed? · one-line reason · existing test path). Call the litmus list_test_types tool for the full map, and search the repo for existing tests before deciding. Then stop and ask the user which types to write in detail.
  2. Design only the confirmed types — load each type's rules with the litmus get_guide tool (or read guides/NN-*.md) first, then write cases. Extend existing tests instead of duplicating.

Treat litmus signals as hints, not verdicts

The test types litmus suggests come from regex over file paths and diffs — it cannot read code semantics. Confirm each suggestion against what the change actually does. A medium confidence signal is "consider"; high is "likely needed".

Writing tests

• Always load the relevant guide before writing cases for that type — call the litmus get_guide tool (e.g. get_guide "unit"), or read guides/NN-*.md. It lists the must-cover cases and the writing principles.
• Test observable behaviour through the public interface; don't mock internal collaborators or test private methods.
• Use /tdd to drive a change test-first.

litmus MCP tools

The plugin runs a small MCP server exposing three tools:

• list_test_types — the full four-level, nine-type map. Start here when unsure.
• get_guide — the full guide for one type; accepts a name, file, number, or alias.
• recommend_guide — suggests guides from a role and/or a short situation.

These read the guides at call time, so guide edits take effect without a rebuild.