phoenix-test

# 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`**.