A grammar for the language forming between humans and language models — documented from field evidence, not folklore.
Prompt-engineering conventions — XML tags, worked examples, "think step by step", role framing — are not tips. They are a pidgin: a contact language that formed spontaneously between two populations (humans and models) because neither's native language was optimal for the exchange. And it is creolizing through a real feedback loop: labs document conventions → users adopt them → the conventions flood the training data → the next model generation is trained to respond to them → the conventions become more true. The language and its reader co-evolve.
This repo is a language-planning project for that creole: a written grammar, with an explicit evidence standard, maintained against real usage.
- SPEC.md — the grammar: 21 conventions across five layers (shape, wording, emphasis, closing the loop, and eight conventions discovered in the field), each tagged with its evidence sources. Plus a frontier list of candidates awaiting a second source.
- STORY.md — how the grammar was found: a prompt compiler that turned out to be the wrong product, a benchmark that hit a ceiling, corpus linguistics on 1,912 real prompts, a 158-file fleet audit, and the discovery that the best-written prompt files already spoke a language nobody had written down. The negative results are kept on purpose.
Four independent evidence sources: [labs] — all major labs' prompting guidance converges on it (convergence encodes internal testing at scales individuals can't run); [field] — it correlates with clean outcomes in a real prompt corpus, or recurs across independently-authored prompt fleets; [mechanism] — it follows from how token-predicting models work; [ours] — it survived a controlled test. A convention needs two sources to enter the grammar. One source = frontier, listed but not law. Conventions can also be demoted: the core exploits training-distribution invariants (structure, examples, position) that every model generation re-learns; the edges churn.
Form is nearly free on short, explicit, one-off prompts — modern models satisfy clearly-stated requirements in almost any format (we measured; see STORY.md). Form pays when prompts are long, complex, or reused — system prompts, agent definitions, skills, standing instruction files — where a small gain compounds across thousands of runs. Write the creole where it compounds.
Living research artifact, evolving. The grammar is maintained against a live fleet (every new prompt file in the source environment is scored against it automatically), so conventions keep getting promoted, demoted, and discovered.
MIT
Built by Dylan Pulver, software engineer and entrepreneur in Toronto.