phoenix-craft

phoenix-craft — write less, change less, prove more

Encodes Andrej Karpathy's observations on LLM coding pitfalls, wired into Phoenix's verify-heal discipline. Biases toward caution over speed; for trivial tasks, use judgment.

Overview

LLMs fail at code in predictable ways: they over-build, "improve" code they were never asked to touch, silently pick one interpretation of an ambiguous ask, and declare success without proof. phoenix-craft is the antidote — four habits, each backed by an objective phoenix_sense check so the virtues are measured, not merely intended.

The four habits

1. Think before coding

Don't assume; don't hide confusion; surface tradeoffs.

• State assumptions explicitly. If uncertain, ask (phoenix-think).
• If multiple interpretations exist, present them — don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop, name what's confusing, ask.

2. Simplicity first

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked. No abstractions for single-use code.
• No "flexibility"/"configurability" that wasn't requested. No error handling for impossible cases.
• If you wrote 200 lines and it could be 50, rewrite it.
• The test: would a senior engineer call this overcomplicated? If yes, simplify — then re-run the acceptance phoenix_sense to prove the simpler version still passes. Simplicity that breaks the check isn't simpler, it's broken.

3. Surgical changes

Touch only what you must; clean up only your own mess.

• Don't "improve" adjacent code, comments, or formatting. Don't refactor what isn't broken.
• Match existing style even if you'd do it differently.
• Remove imports/vars/functions your change orphaned; leave pre-existing dead code (mention it).
• The test: every changed line traces directly to the request. Verify the diff is minimal before sensing — a bloated diff breaks unrelated checks and pollutes the blast radius.