Murphy

Makes your coding agent assume everything will go wrong.

An Agent Skill for finding, fixing, and proving the unhappy paths that happy-path code reviews miss.

The bug usually lives after “what if?”

Your checkout works when the provider replies. What if the charge succeeds and the reply is lost? Your file exporter works on a clean disk. What if the disk fills halfway through the write?

Murphy makes a coding agent trace the real user promise, select the few failures that matter, and refuse to call them fixed until the failure has been forced and recovery observed.

happy path                         Murphy
-----------                        ------
request -> success                 promise -> boundary -> forced failure
test passes                        -> recovery -> forbidden side effects
"handles errors"                   proven / partial / unproven

Five-minute start

Install directly from GitHub with the open Agent Skills CLI:

npx skills add fish34851-hash/murphy --skill murphy

Then ask your coding agent:

Use $murphy to harden checkout submission. Map the highest-risk failures,
implement the missing protections, and prove the recovery at the user surface.

Murphy supports Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, and other clients that understand the Agent Skills format.

What changes in the answer

Ordinary review	Murphy
“Add error handling.”	“If the provider accepts the charge but its response times out, keep the order pending and reuse the same idempotency key.”
“Test edge cases.”	Force the acknowledgement timeout; assert one provider effect and the visible retry state.
A long generic checklist	3–7 failures selected from the actual path by impact and likelihood.
Passing happy-path tests	Each row is labeled proven, partially proven, or unproven.

See the complete checkout failure matrix.

Three natural modes

• Map: “What can go wrong with this upload flow?” Murphy reports a prioritized failure matrix and leaves the code untouched.
• Build: “Make this import resumable.” Murphy maps the failures, makes the smallest relevant changes, and forces the break.
• Review: “Did this PR make retries safe?” Murphy inspects the real path and separates evidence from inference.

There are no slash commands to memorize. The request determines the mode.

A tiny mechanical gate

The skill does the reasoning. The bundled zero-dependency CLI keeps saved matrices honest.

# Create a matrix without overwriting an existing file
node bin/murphy.mjs init FAILURE_MATRIX.md --feature "Checkout submission"

# Reject placeholders and vague proof
node bin/murphy.mjs check FAILURE_MATRIX.md

# Machine-readable output for CI
node bin/murphy.mjs check FAILURE_MATRIX.md --json

Example output:

FAIL  FAILURE_MATRIX.md  (1 rows)
  error: FM-01: expected behavior is too vague ("handle gracefully").
  error: FM-01: proof is too vague ("covered by tests").

The rule

Every selected failure needs three things:

1. A forceable trigger — not “the API breaks,” but “the provider accepts the charge and the acknowledgement times out.”
2. An observable promise — exact state, preserved data, message, and safe recovery action.
3. A proof with a negative assertion — recovery happened and the forbidden side effect did not.

Murphy will not inject chaos into production, spend money to manufacture a failure, or turn an unsafe experiment into “proof.” Unsafe or unavailable seams remain explicitly unproven.

Project shape

murphy/
├── SKILL.md                    agent-facing workflow
├── references/                failure catalog and proof patterns
├── assets/failure-matrix.md   reusable artifact template
├── bin/murphy.mjs             zero-dependency matrix checker
├── examples/                  concrete before/after evidence
└── test/                      CLI behavior tests

Design principles

• The feature's promise comes before the checklist.
• Three credible failures beat thirty imaginary ones.
• A happy-path test cannot prove an unhappy path.
• “Graceful” is not an observable behavior.
• No benchmark number appears here unless anyone can reproduce it.

Development

Requires Node.js 18 or newer only for the optional checker. The skill itself is Markdown.

npm test
npm run check:example
npm pack --dry-run

CI runs the suite on Linux, macOS, and Windows across Node.js 18, 20, and 22. Contributions are welcome; read CONTRIBUTING.md before adding new rules.

License

MIT. If Murphy catches the failure your happy path missed, consider starring the repository and sharing the matrix.