interpret-test-failure

name	interpret-test-failure
description	Read a Vitest error, query test_history for prior occurrences, extract assertion shape, and compute a failure signature. Use when a test fails and you need to decide whether it's a new failure, a recurring known one, or flaky.

Interpret a test failure

When a test fails, do the following:

1. Read the assertion message and stack trace. The MCP test_errors tool returns these. Identify:
   • The assertion matcher (toBe, toEqual, toThrow, etc.)
   • The expected vs actual values (or value shapes)
   • The top non-framework stack frame (skip node:internal, node_modules/vitest/)
2. Query history. Call test_history({ project: ..., subProject: ... }) to see if this test has failed before. Look for the test's fullName in the records.
3. Get the failure signature. Call failure_signature_get({ hash }) if the error has a recorded signature. Recurring signatures collapse to one row; the occurrence_count tells you how often this failure has been seen.
4. Classify. Combine the history and signature data:
   • new-failure — first time seeing this test fail
   • persistent — failed in two or more consecutive runs
   • flaky — mixed pass/fail across recent runs
   • recovered — was failing, now passing
   • stable — consistently passing

Use the classification to decide your next action. New failures need a hypothesis. Persistent failures may indicate a real bug or a structural test issue. Flaky tests should not be silenced — investigate the source of nondeterminism.

Reusable outside TDD

This skill is not TDD-specific. The fix-failing-test and flaky-triage workflows both use it.