mutation-testing

name	mutation-testing
description	Run mutant, read mutation reports, fix alive mutations, and verify coverage. Use when running mutation testing, responding to alive mutations, or improving test quality. Triggers: "mutation testing", "mutant", "alive mutation", "mutation coverage". WHEN NOT: Writing tests from scratch (use rspec-agent), fixing failing tests, or general code review.
context	fork
agent	general-purpose
model	sonnet
allowed-tools	Read, Write, Edit, Grep, Glob, Bash
user-invocable	true
argument-hint	[subject expression, e.g. Entities::CreateService#call]

Mutation Testing with Mutant

When to Activate

• The user asks to run mutation testing.
• The user has alive mutations to fix.
• The user asks to verify mutation coverage on a subject.

When Not to Use

• The task does not involve mutation testing.

Inputs

• Alive mutation output to act on (paste the evil: block).
• Optional: subject expression to scope the run.

Outputs (Fixed Order)

1. Mutation results (alive count, coverage percentage).
2. Clear action for each alive mutation: add test or simplify code.

---

Reading Mutation Output

An alive mutation looks like:

evil:YourClass#method:YourClass#method:lib/your_class.rb:42:abc12
@@ -1,3 +1,3 @@
 def method
-  @value >= threshold
+  @value > threshold
 end

• evil means no test killed this mutation.
• The diff shows original (-) and mutated (+) code.

---

Reporting Format (BLUF)

Lead with the verdict — bottom line up front:

If unkillable:

Unkillable. Both forms are equivalent because [reason]. Add to ignore list.

If killable:

Killable.

Option A — add test:

(test diff)

Option B — simplify code:

(source diff)

Always present both options so the user can choose. Include evidence: if you cannot think of a test that would kill the mutation, say so — that is valuable signal toward unkillable.

---

Usage

1. Run Mutant

bundle exec mutant run --fail-fast

When the subject is known, scope the run to avoid testing unrelated subjects:

bundle exec mutant run --fail-fast 'Entities::CreateService#call'

If the command succeeds, coverage is 100% — done. If it fails, find the evil: line in the output — it has the subject name, file path, and line number. The diff block immediately after shows the original and mutated code.