> Markdown rendition of https://typeglish.dev/docs/score ("TG score — TypeGlish docs"). Canonical page: https://typeglish.dev/docs/score · All pages: https://typeglish.dev/docs/llms.txt

Optimizing

# TG score

The TG score grades a prompt A–F from eight facets (nine with the advisory density tier). It’s deterministic and explainable — no model in the loop for the grade; the advisory density facet is model-backed and never gates.

## The score facets

The TG score is a weighted blend of eight facets (nine with the advisory density tier) across a `runtime` plane (what the model reads) and a `hygiene` plane (how the source reads). Explain any facet with `typeglish --explain <facet>`; `typeglish review <file>` ranks the fixes that would raise each one.

| Facet | What it measures | What raises it |
| --- | --- | --- |
| `enforceability` · runtime · w0.25 | How much of the prompt the checker can READ as rules. Three shares: rule-shaped lines it reads at all (a line needs a modal — MUST / NEVER / SHOULD — or a catalog verb at its head; an IF … THEN needs the modal INSIDE the branch; a frequency word like USUALLY is not a modal), hard rules it can PROVE (one catalog verb, one object, or a numeric bound — a trailing "before / and / or" clause, an adverb before the verb, or an unknown verb stops the proof), and rules that are measurable (an observable action or bound). Facts (`All refunds are approved.`) and $SWITCH arm bodies count as unread lines here. | Lead every rule with a modal — MUST / NEVER / SHOULD — or put it after THEN; one action and one object per line, a verb the checker knows or a bound ("at most 3 sentences"). Descriptive detail with no bound does not move this facet. `typeglish score <file>` prints the rules table with the edit per line; `typeglish --explain enforceability <file>` prints just that table. |
| `hardness` · runtime · w0.15 | THE HARDNESS DOCTRINE (SPEC §15): how BINDING the prompt's language is. Every force word sits on a spectrum (must not ↔ must, never ↔ always, no ↔ all); hardness is its distance from the waver center (THE POLE LAW — both poles bind, the middle wavers), and a statement scores the MIN over its force words (one hedge softens the whole rule). An unhedged command is 1.0; 1.0 renders PURE BOLD in the editor. | Commit to pole words — MUST / NEVER / ALWAYS / ALL / exact bounds ("at most 3") — and delete the soft middle: should, sometimes, about, try to, as needed each cap their statement below 1.0. |
| `directness` · runtime · w0.1 | THE DIRECTNESS AXIS (SPEC §15's sibling): explicit beats implicit. A statement is only as actionable as its encoded DOER (imperative/you > named > definite party > generic > by-passive > agentless passive > nominalization) and its RESOLVED pointers (a pro-form with no referent is a guess). Directness is the MIN over the two channels, averaged over action-shaped statements; states abstain. | Use the imperative or a named doer ("Verify the order.", "You must ..."), keep the active voice (not "is verified" / "a review must take place"), and make every it/this point at something the prompt introduced. |
| `density` · runtime · w0.2 | Advisory, model-backed: information per token — mean residual value + non-redundancy from the semantic tier. Moves the number, never the gate; present only when the semantic report ran. | Delete the lines the ablation marks removable and merge overlapping rules. |
| `consistency` · runtime · w0.2 | Deductions from logic/* and clarity/* findings — contradictions, dead rules, duplicates — rated per statement. | Fix the ledger rows with logic/ or clarity/ codes; state each fact in one place. |
| `structure` · hygiene · w0.15 | Deductions from structure/* and typeglish/* findings — indentation, sections, references, terminators — rated per statement. (hygiene plane: authoring discipline) | Fix the ledger rows with structure/ codes; most carry a one-click fix. |
| `annotation` · hygiene · w0.15 | Statement-documentation coverage: annotated statements over eligible statements — every statement should carry a @@ note saying what it is FOR. Source-only: @@ notes are stripped at compile. (hygiene plane) | Put a "@@ why" note directly above each statement ("@@ name: why" also names it). |
| `style` · runtime · w0.1 | Deductions from style/*, prompt/*, spelling/*, grammar/* findings — hedging, vagueness, wordiness, typos — rated per statement. These SHIP: the flagged prose is what the model reads. | Commit to modals, delete hedges, and apply the flagged rewrites. |
| `security` · runtime · w0.1 | Deductions from security/* findings — injection-shaped text and credential literals (a leaked secret also caps the grade at F). | Remove secrets and injection scaffolding from the prompt; secrets belong in the host environment (@{env.NAME} in tool bindings). |

✓ The score gates CI: `typeglish score <file> --min B` exits non-zero below the floor, and the output names the biggest lever.