| name | llm-mutest-go |
| description | Given a bug report and a Go source file, writes a mutation-tested regression proof on a bugfix branch using gremlins. Invoke when asked to mutation-test a bug, validate a bugfix, or prove a regression test is meaningful. |
| license | MIT |
| metadata | {"language":"go","workflow":"bug-validation"} |
Prerequisites — check all before starting
| What | Check | If missing |
|---|
| Bug report | Attached or pasted by user | Ask for it. Do not proceed. |
| Source file | Named in the bug report | Ask for the path. Do not proceed. |
| Gremlins | gremlins unleash --version | Ask to install: go install github.com/go-gremlins/gremlins/cmd/gremlins@latest |
| Bugfix branch | git branch --show-current | If on main/master, ask to create or switch. |
Steps
1. Parse the bug report Extract: affected function, root cause, expected vs actual behaviour. Summarise in one
sentence. Ask if ambiguous.
2. Read the source file Find the buggy function. Note its signature, package name, and any same-package helpers it
uses.
3. Write the regression test → <file>_bugfix_test.go
- One
func TestBugfix_<Fn>_<Description>(t *testing.T)
- Table-driven, rows named after the bug (
"bug: off-by-one on last element")
package <pkg>_test unless internal access is needed- stdlib only — no third-party helpers
- Must be red on buggy code:
go test ./... -run TestBugfix_... → FAIL. Revise if it passes.
4. Apply the fix (skip if user already has one) Propose a minimal diff. Ask for confirmation. Apply only the
targeted change.
5. Verify green go test ./... -run TestBugfix_... → must PASS. Do not continue until it does.
6. Run gremlins (scoped to the affected file — never run unscoped on large modules)
gremlins unleash --tags <file>.go --coverpkg ./...
7. Kill surviving mutants For each LIVED/NOT COVERED mutant in the affected function:
- Describe what changed and why the test missed it.
- Add a table row or new test to kill it.
- Re-run gremlins. Repeat up to 3 rounds. After 3, mark remaining as equivalent mutants and stop.
8. Report
Bug: <one-liner>
File: <path> Function: <name> Branch: <branch>
Test: <file>_bugfix_test.go — red before fix ✓ green after ✓
Gremlins: X/X killed in affected function
Survivors: none ✓ (or list with explanation)
Rules
- Never touch
main/master directly.
NOT COVERED for all mutants = test isn't hitting the right code path — check package and run filter.- Equivalent mutants are acceptable survivors — document them.
