all-the-vibes/atv-phoenix/phoenix-think

phoenix-think — understand deeply, then define "done" objectively

_The most expensive bug is building the wrong thing correctly._

Most agents skip straight to code on a half-understood ask and produce something plausible but wrong. phoenix-think is the antidote: it spends cheap thinking-tokens up front to (1) extract what the user actually wants, (2) ground it in real evidence from the codebase and the world, and (3) crystallize it into an intent whose finish line is a runnable objective check — the gate the rest of the Phoenix lifecycle (plan → build → review → ship) verifies against. No check, no proceed.

This stage is deliberately rich. Rushing it is the false economy this whole harness exists to prevent.

Three movements (do them in order; loop until clarity)

1. ELICIT — Socratic deep interview (extract intent, don't assume it)

Ask one focused question at a time, each targeting the highest-uncertainty unknown. Prefer questions that expose hidden assumptions over questions that confirm what you already believe. Cover, as relevant:

• Outcome: What does success look like to you? How will you know it worked? (push for an

observable signal, not a feeling)

• Boundaries: What is explicitly OUT of scope? What must NOT change or break?
• Constraints: performance, privacy, budget (calls/$), reversibility, deadline, who else is affected.
• Context & priors: Is there existing code, a convention, a past attempt, a preferred approach?
• Edge cases & failure: What inputs/states worry you? What does "wrong" look like?
• Hidden assumptions: State the assumptions you're making back to the user and ask them to confirm

or correct each one. ("I'm assuming X — is that right?")

Track an informal ambiguity score: how much could still go wrong if you executed now? Keep interviewing until that risk is low. Stop early if the user says "just do it" — respect their intent, but state the top 1–2 assumptions you're proceeding on.

2. GROUND — evidence-grounded deep research (replace guesses with facts)

Do not theorize on assumptions. Investigate before deciding:

• Codebase: read the relevant code, conventions, tests, and prior art. Use structural retrieval

(the bundled TokenMasterX graph: who-calls / what-breaks-if-I-change) to find the real blast radius instead of grepping blind. Identify the existing pattern to follow, not a generic default.

• Project memory/conventions: check for project-specific rules the model can't guess (naming,

formats, idioms). A correct-looking default that violates a convention is a silent failure (see H3).

• External (when the task needs it): verify SDK/framework/API behavior against primary docs, not

recall. Cite what you find; flag anything you could not verify as unverified.

• Record what you learned and — crucially — what you still don't know. Unknowns are honest and

steer the next interview question.

3. CRYSTALLIZE — the Intent Contract + the acceptance gate (the Phoenix payload)

Converge everything above into a short, explicit contract:

INTENT (raw):       <the user's words, verbatim — never silently reinterpret>
GOAL (world-state): <the observable end-state: "X is true", not "do X">
ACCEPTANCE CHECK:   <a runnable phoenix_sense check that passes iff the goal is met>
                    e.g. {"kind":"command_exit","target":["pytest","-q","tests/test_x.py"],"expect":0}
CONSTRAINTS:        privacy · budget · reversibility · scope-out
ASSUMPTIONS:        <confirmed-with-user list; the risks you're proceeding on>
OPEN QUESTIONS:     <what's still unknown, and how you'll resolve it>

The acceptance check is the deliverable of this stage. It is what phoenix-ship will re-run before anyone is allowed to say "done." If no test exists yet, the contract names "write that test" as the first build step — because the check defines done.

The hard rule

Do not hand off to phoenix-plan until you have an acceptance check you could run today and watch fail on the unbuilt work. A gate that cannot fail measures nothing. If success genuinely cannot be made objective (a pure judgment call), say so explicitly and name the strongest objective proxy you can — never pretend a vibe is a verified outcome.

Calibrate the depth (don't over-interview a trivial ask)

• Trivial / precise ask (file paths, exact behavior, existing acceptance criteria): skip the

interview, do a quick codebase ground-check, write the one-line check, proceed.

• Standard ask: a few sharp questions + a focused codebase read.
• Vague / high-stakes / "interview me": the full three movements, multiple interview rounds, deep

research, explicit assumption confirmation.

Honesty

Surface assumptions instead of burying them. Report "unknown" rather than guessing. The output of good thinking is not certainty — it is a correctly-scoped intent with an objective finish line and the risks named out loud.

Next

Hand the Intent Contract to `phoenix-plan`, which decomposes it into small, individually-verifiable steps that compose up to the acceptance check.