The cycle as things you type. Each one comes with what a good
answer looks like, so you can judge the reply, and the mistake it's meant to head off.
They're in rough order of use. If you only take two, take the cold start and the
reconcile prompt.
Orient
Cold start: read the doc, not the codebase
Read ONTOLOGY.md in <app>/ and tell me what this system is for, what its
main entities are, and where you think the design risk sits. Don't read the
implementation yet.
A good answer summarizes the system in the domain's own words
and names a risk. If it can't, the document isn't pulling its weight, and you found
that out in one call.
Heads off a session that greps its way to a guess.
Start
Purpose before entities
/ontology_spec new app: <one-line idea>
Ask me the §0 questions first — what this is for, the qualities a user should
feel, the goals in priority order, and the non-goals. Don't write entities
until I've answered.
A good answer is a short batch of questions, not a draft
spec.
Heads off a document whose purpose was inferred. §0
breaks ties for everything that comes after, so if it's a guess, the ties break the
model's way.
Start
Rules and their test cases together
Write ONTOLOGY's entities and rules alongside the CRITERIA rows — each rule
next to its Given/Expect case. Keep every rule under ten lines of pseudocode,
mark every number [T], and tag [D] or [P] honestly.
A good answer keeps the rules inside ten lines. If one won't
fit, that's useful to know: it's probably too vague to implement yet.
Heads off criteria written afterwards, which tend to
justify the rules rather than test them.
Convert
Map an existing spec before touching it
/ontology_spec convert docs/SPEC.md
Map first, no edits: old section → new ID. Where the spec and the code
disagree, the code wins and the discrepancy goes in a list for me to rule on.
Show me the map before you rewrite anything.
A good answer is a mapping table and a list of discrepancies,
with nothing rewritten yet. Anything that has no home in the map is usually the
interesting part.
Heads off drift being quietly resolved in whichever
direction the model guessed.
Build
Contract first, UI last
/implement <app>
Contract first — the commands and events table — then the headless core with
seeded, DOM-free tests, then tune against a committed harness, then the UI.
A good answer settles the commands and events before any engine
code exists, with each command checking its own legality.
Heads off an interface invented during implementation,
which is where most of them come from and why they're hard to animate or network
later.
Review
Questions in one batch
Collect every open question as Q-n with its options and your recommendation,
and send them to me in one message. Stop on anything blocking rather than
picking for me.
A good answer is one message, numbered, each question carrying a
recommendation you can take or override in a sentence.
Heads off the drip: one question per turn, each answered
without the others in view.
Reconcile
Four things move together
For this change, update together: the ONTOLOGY rule, the CRITERIA row,
test/R-n/, and a dated ARCHITECTURE_LOG entry carrying the reasoning. Don't
hand it back until all four have moved.
A good answer is one diff touching all four. A missing log entry
means the change isn't finished, since a log written later isn't really a log.
Heads off docs drifting from code, which is how you end
up back at the UML problem. Probably the prompt that earns the most here.
Measure
No claim without evidence
No balance or performance claim enters the log without an Evidence line:
"Measured by: <command> → <result>", or "Modeled by: <sim> (unverified)".
Change one named constant at a time so the attribution isn't confounded.
A good answer declines to assert a tuning outcome that nothing
ran, and labels modeled numbers as modeled.
Heads off confident predictions. One simulation here
predicted 4–8 shots per encounter; the real game gave 2.
Audit
Does each thing still do what it's for?
/ontology_spec teleology
For each entity and rule, does it still do what its Serves tag says? Measure,
don't read — toggle it, halve it, double it — and name the command behind every
finding. Recommend, but leave design fixes to me.
A good answer is a table of verdicts — Served, Half drifted,
Drifted, Unverified — plus the reverse check: goals nothing serves, purposes with no
state behind them.
Heads off mechanics that have quietly started serving
something other than their stated purpose.
These assume the documents they're driving. If something here is unfamiliar —
Serves:, the four instrument forms, test/R-n/ —
the doc set is the reference card.
And if you'd rather know the cost before adopting any of it, that's on
objections and costs.