phoenix-test

type	Phoenix Skill
name	phoenix-test
description	Drive development and bug-fixing with tests where the test IS the objective phoenix_sense gate. Write a failing test before the code, reproduce a bug with a test before fixing it, and let phoenix_sense decide pass/fail — never "looks right". Use when implementing logic, fixing a bug, changing behavior, or when the user says /phoenix-test, "write tests", or "TDD".
license	MIT

phoenix-test — the test is the gate; red→green is proven, not asserted

Overview

Write a failing test before the code that makes it pass. For a bug, reproduce it with a test before attempting a fix. In Phoenix, the test is not a suggestion — it is the literal phoenix_sense check that gates the work. "Seems right" is never done; a red→green transition you watched happen is. A codebase with tests is the agent's superpower because it converts judgment into objective signal.

When to use

• Implementing any new logic or behavior.
• Fixing any bug (the Prove-It Pattern below).
• Modifying existing functionality or adding edge-case handling.

When NOT to use: pure config/doc/static changes with no behavioral impact (a lint sense is enough).

The cycle — RED → GREEN → REFACTOR, each step a phoenix_sense

   RED                    GREEN                  REFACTOR
 write a test        write minimal code        clean up, no
 that FAILS    ──►    to make it pass     ──►   behavior change   ──► (repeat)
     │                     │                         │
 phoenix_sense        phoenix_sense             phoenix_sense
   = ok:false           = ok:true              = still ok:true

1. RED — write the failing test, and sense it fail

A test that passes immediately proves nothing. Run it and confirm red:

phoenix_sense {"kind":"command_exit","target":["pytest","-q","tests/test_task.py::test_create"],"expect":0}
# -> {"ok":false}   ← REQUIRED. If this is green, the test isn't testing the new behavior.

2. GREEN — minimal code, then sense it pass

Write the least code that turns the check green. Don't over-engineer. Re-sense the same check → ok:true.

3. REFACTOR — improve with the check as a guardrail

phoenix_snapshot the file, refactor, phoenix_sense after each change. If a refactor goes red, phoenix_heal rollback — the refactor is supposed to be behavior-preserving, so red means you changed behavior. Roll back and try a smaller refactor.

The Prove-It Pattern (bug fixes)

When a bug is reported, do not start by fixing it. Start by reproducing it as a test:

Bug report ─► write a test that reproduces it ─► phoenix_sense = ok:false (bug confirmed)
           ─► fix the code ─► phoenix_sense = ok:true (bug fixed, and now regression-guarded forever)

The failing test does three jobs: it proves the bug exists, proves your fix works, and prevents the bug from coming back. A "fix" with no reproducing test is a guess.

Token-efficiency note

Run the narrowest check that proves the step (a single test id), not the whole suite, during the inner loop — fast feedback, cheap tokens. Sense the full suite once at the end (and in phoenix-review).

Common Rationalizations

Rationalization	Reality
"I'll write the test after the code."	Test-after rarely fails first, so it proves nothing and often just encodes the bug you shipped.
"I can see the test would pass, no need to run RED."	A test you didn't watch fail might be testing nothing (typo'd assertion, wrong import). Sense the red.
"This bug is obvious, I'll just patch it."	~30% of "obvious" fixes are wrong or incomplete. A reproducing test is the cheap insurance.
"The test is flaky, I'll skip it."	Flaky tests mask real bugs. phoenix_heal retry to see if it's transient; if it's real, fix it.
"Refactor doesn't need re-testing."	Refactor means behavior-preserving — the only way to know it preserved behavior is to sense the test green.

Red Flags

• A new test passed on the first run. → It probably isn't exercising the new behavior. Make it fail first.
• You're fixing a bug with no reproducing test. → Write the test; sense it red before you fix.
• You edited the test to match the code's current (wrong) output. → That's encoding the bug. Revert.
• You only ever run the full suite. → Use a narrow check in the inner loop for cheap, fast feedback.

Next

With the behavior proven, continue in phoenix-build for remaining steps, or phoenix-review when the feature is complete. A red you can't explain → phoenix-debug.