SyntaxForge

An AI follows your prompt word for word, and fills every gap with a guess. This tool reads your prompt like a strict reviewer. It points out where the AI would have to guess, where two instructions clash, and where the wording is too soft to be followed reliably.

Nothing you type leaves your computer.

1. Paste your prompt into the big box on the left, or start from our example.
2. Look at the grade in the circle. A is great. F means something must be fixed.
3. Open Top fixes and fix the first item. The grade updates as you type.
4. Click any line number, like L12, to jump to that line.
5. Repeat until you're happy. Undo appears in the toolbar if you change your mind.

Colors

• Red: must fix Two instructions clash, a number limit is unreadable, or a secret is exposed. Any red item drops the grade to F and the score to 49 or less, and empties the bar of the check it belongs to.
• Yellow: should fix The AI may guess or skip something. These lower your score.
• Blue: tips Small improvements, like spacing or soft wording.

The eight checks behind the grade

• Firm: use these MUST, NEVER, ALWAYS, DO NOT
• Soft: only for true preferences should, may, prefer
• Weak: remove them try to, if possible, maybe, ideally, hopefully
• Vague: replace with specifics appropriate, relevant, properly, as needed, etc.
• "How often" words: use IF … THEN instead sometimes, usually, rarely
• AI-sounding: say it plainly long dashes (—), you are not X, you are Y, elite, seamless, delve, feel free to

Use IF (or WHEN) for the situation, then THEN for what to do:

IF the user is angry THEN You MUST apologize once.
WHEN the user asks about a refund THEN You MUST transfer the chat to 'billing_agent'.

Without THEN, the AI knows the situation but not what to do.

Put names in quotes at the start of a line, under a heading. Then use the same spelling everywhere.

# Agent Registry
- 'billing_agent': agent that handles invoices and refunds.
- 'tech_agent': agent that handles login problems.

# Variables
- 'is_vip' is boolean.
- 'order_total' is number.

The Names tab lists everything you defined. If a rule uses a name you forgot to define, you'll see Name used but never defined.

• Top fixes: the changes that raise your grade most, in order.
• Instructions: every line read as an instruction, marked clear, hard to check, or not an instruction yet.
• Names: the helpers and facts your prompt defines.
• Try it: pretend a customer writes in and see which helper the AI would hand the chat to. It never changes your grade.
• Issues: everything found, with how to fix it. "Show technical detail" reveals the engine's own wording.

Once you know these habits, switch to Intermediate. You'll see the same issues with their technical names alongside the plain explanation. That makes it easier to discuss prompts with engineers.

Each finding shows three things:

• The technical code, like undeclared-entity. Engineers and the exported file use this name.
• The engine's original message, word for word.
• In plain words, with a one-line Fix.

Every code the engine can report. The first part of the code is the area: logic, clarity, prompt, structure, grammar, style, security, literal (AI-sounding phrasing), or nlp (optional hints).

# Role
You are a <role>.

# Agent Registry
- '<agent_name>': agent that <does what>.

# Variables
- '<flag_name>' is boolean.
- '<tier>' is one of 'gold', 'silver'.

# Rules
- You MUST <action> <object>.
- You NEVER <action> <object>.
- IF '<flag_name>' is true THEN You MUST <action>.

# Routing
- WHEN <situation> THEN You MUST transfer the chat to '<agent_name>'.

Errors, warnings, and notes subtract points from their check, scaled by the prompt's length. Literalness is the exception: each match costs a fixed number of points, up to a cap per pattern. The optional NLP hints never affect the grade.

Errors. Any error (red) drops the grade to F and the score to 49 or less, and sets the check it belongs to to 0: a contradiction empties "No contradictions", an unreadable number limit empties "Tidy layout", a leaked key empties "No secrets leaked".

Grade caps. A check that scores too low limits the grade, however good the rest is. Today: "Can it be checked?" (Enforceability) below 80 caps the grade at B, below 60 at C; "Says it plainly" (Literalness) below 70 caps it at B, below 40 at C. The number is lowered to the top of that grade (89 for B, 79 for C), and the first item in Fixes says how to lift the cap.

Weights, grade bands, and caps are shipped in grammar/scoring.yaml.

Switch to Expert when you want the technical output only, the full parser reference, or the exported AST format for engineering handoff.

Line Types & Classifications

• Structural Headings (# Role, ### Constraints): Organizes context sections. Treated as metadata, not scored constraints.
• Declarations ('risk_flag' is boolean, - 'billing_agent': handles invoices): Binds a variable, agent, or tool to a definition. Only a quoted name or pointer at the start of a top-level line registers in the Entities schema (see section 8).
• Assignments (IF 'risk_flag' is true THEN 'current_risk' is true): Changes runtime state when a condition holds. Assignments never declare a variable; the variable must already exist in the schema.
• Pointers (@{variable}, @[tool]): Use formal pointers to reference declared entities, variables, or system tools. The compiler treats these as unbreakable atomic references.
• Conditionals (IF / WHEN / UNLESS / WHILE / WHENEVER … THEN): Establishes a trigger boundary. Directs the AI to only activate the rule when the condition evaluates to true. A condition line with nothing after THEN opens a block: every more-indented line below it belongs to that condition.
• Directives (MUST …, NEVER …): Actionable commands. These are the *only* lines that populate the Rules Tab.
• Prose / Persona (You are a helpful assistant): Background setup. Ignored by the contradiction engine because prose cannot be mathematically tested.

Why does the Rules Tab not always start at Line 1?

If Lines 1 through 10 are headings, role descriptions, and data declarations, they are structural. The engine only surfaces a line in the Rules tab once it encounters an actionable directive (e.g., Line 11: You MUST follow below instructions:). The tab displays verified rules, not raw editor line numbers.

Hard Constraints (Passes Enforceability)

• Obligations MUST, ALWAYS, REQUIRE, ENSURE
• Prohibitions NEVER, MUST NOT, MUST NEVER, DO NOT, DON'T, MUSTN'T, CANNOT, CAN'T

Soft Constraints (Penalizes Hardness KPI)

• Recommendations SHOULD, PREFER, MAY
• Discouraged SHOULD NOT, SHOULDN'T, AVOID

Trigger Words (Penalizes Logic & Enforceability KPIs)

• Frequency Overrides sometimes, occasionally, at times, usually, mostly, generally, typically, rarely, seldom.
  (Note: Using these alongside ALWAYS/NEVER triggers a logical contradiction).
• Hedging try to, attempt to, if possible, where possible, whenever possible, when possible, as much as possible, if you can, ideally, perhaps, maybe, hopefully. (grammar/wording.yaml)
• Vague Judgments as needed, appropriately, appropriate, properly, proper, relevant, etc, reasonable, reasonably, suitable, suitably, adequate, adequately, sufficient, sufficiently, as appropriate, where necessary, if necessary, and so on, various. (grammar/wording.yaml)

• Communication: say, speak, tell, state, mention, imply, quote, name, acknowledge, respond, reply, answer, explain, describe, clarify, elaborate, summarize, repeat, suggest, recommend, warn, inform, notify, remind, apologize, thank, ask, request, prompt, confirm, deny, verify, double-check, greet, welcome, talk, contact
• Output & Presentation: output, emit, print, display, show, send, include, return, provide, offer, give, share, present, list, cite, reference, link, reveal
• Suppression & Privacy: withhold, suppress, hide, omit, block, skip, exclude, redact, censor, avoid, refrain
• Data & State: check, search, fetch, pull, find, locate, retrieve, query, load, capture, record, store, save, hold, collect, gather, log, track, read, write
• Routing & Lifecycle: transfer, escalate, forward, redirect, start, begin, stop, halt, cease, allow, permit, forbid, wait, pause, delay, stall, open, close, join, leave, schedule, cancel
• Transformation & Creation: make, create, build, generate, produce, draft, compose, prepare, add, insert, append, attach, put, place, update, change, modify, edit, set, replace, rename, convert, translate, rewrite, refactor, debug, reword, fix, correct, adjust, trim, shorten, expand, remove, delete, strip, discard, clear, format, structure, organize, arrange, sort, group, capitalize, indent
• Cognitive & Evaluation: review, analyze, evaluate, assess, think, learn, teach, look, listen, watch, see, feel, try, decide, plan, act, behave, choose, select, pick
• Business & Support: handle, issue, receive, process, resolve, help, support, solve, protect, pay, buy, sell, book, refund, charge, bill, sign, meet, visit, serve, assist, guide, lead
• Logic & Compliance: follow, adhere, comply, stick, obey, respect, honor, match, mirror, approve, reject, accept, decline, grant, refuse, ensure, remember, recall, consider, assume, treat, prioritize, focus, ignore, disregard, keep, maintain, preserve, retain
• Light Verbs (Object Required): fire, call, invoke, run, trigger, execute, use, perform, apply, do, have, take, bring, move, turn, point, lower, raise, let, get, go, come, stay, remain, be. (These cannot stand alone; they must name their target object, e.g., "MUST execute the plan").

• Numerical Bounds: at most 3 sentences vs at least 5 sentences. Both cannot simultaneously be satisfied.
• Temporal Windows: within 90 seconds vs at least 2 minutes. Units of time are converted before comparing.
• Monetary Thresholds: at most 50 USD vs at least 100 USD.
• Cardinality: Declaring There is only one tool alongside There are several tools.
• Quantifier Squares: Directing All refunds are approved alongside No refunds are approved.
• Deadlocks: MUST send the survey before you close the chat alongside MUST close the chat before you send the survey. Rules under exclusive conditions (IF 'vip' is true / OTHERWISE) keep separate timelines and never deadlock.
• Ranking Loops: 'gold' is higher priority than 'silver' alongside 'silver' is higher priority than 'gold'.
• Bypassed Gates: MAY issue a refund only if 'verified' is true alongside an unconditional MUST issue a refund (logic/only-gate).

How bounds are compared. Each bound becomes a range: at most 3 is [0, 3], at least 5 is [5, ∞), less than 3 is [0, 3). A prohibition flips it: NEVER write more than 3 sentences is [0, 3]. Two ranges on the same unit, under the same conditions, that do not overlap are a contradiction when at least one of the two rules is hard.

Bound syntax is strict. A number in a rule must be written as comparator + number + unit, all from the grammar (grammar/comparators.yaml, grammar/units.yaml): at most 3 sentences, exactly 2 options, within 5 minutes. Anything else (list 3 options, at most $50, at most 1 clarifying question) is a syntax/invalid-bound error.

How does the engine handle and / or in directives?

The engine utilizes a Recursive Descent Parser to build an Abstract Syntax Tree (AST) in memory. This means it physically maps the grammatical branches of your sentence rather than just scanning for keywords.

When you write a compound statement like "You MUST classify @{query} AND select @{agent}", the AST automatically decouples the sentence into distinct execution branches:

• Branch 1: MUST → classify → @{query}
• Branch 2: MUST → select → @{agent}

The Result: You can safely write natural, token-efficient compound sentences without breaking the contradiction engine. If Line 80 says "NEVER select @{agent}", the compiler will mathematically cross-reference the AST branches and instantly catch the collision against the second half of your compound statement.

The NLP hints button turns on a second opinion from compromise.js, a small part-of-speech tagger that ships with this app and runs offline in your browser. Its notes appear under Notes in the Findings tab. They never change the score: the grade comes only from the deterministic rules and the verb catalog above.

• passive "The inquiry is to be escalated by the agent" → "You MUST escalate …"
• verb-synonym "MUST utilize the search tool": "utilize" is a verb but not in the catalog; nearest catalog verb is use.
• verb-position "MUST in every reply cite the source": the verb is "cite"; lead with it.
• future "The agent will greet the user" describes behaviour; write "You MUST greet …".
• compound "…verify the identity and update records": "update" could be a noun or a verb. The rule reader treats it as a list item, and the tagger says it reads as a verb, so check whether this is two actions.

Tier 1: What counts as a declaration

A name enters the schema only when all of these hold:

• It is a quoted name ('risk_flag') or a pointer (@{query}, @[search_kb]) at the start of a line or bullet.
• It is followed by is, are, :, =, or means.
• It sits at the top level. Anything inside an IF condition or a THEN outcome, inline or in an indented block, is never registered.

Under a heading such as # Agent Registry, # Variables, or # Tools, bare bullet names also register (- risk_flag: boolean). JSON inside code fences or brace blocks is ignored.

The engine infers a kind for each entry. It uses the heading (agents, tools, variables), the pointer type (@[…] is a tool, @<…> is an agent), and the definition (boolean, number, one of 'a', 'b', default to …).

Tier 2: Undeclared variables

Every pointer, and every quoted name shaped like a variable (snake_case, dotted.path, camelCase, or `backticked`), is checked against the schema. So is any quoted name on the left of a condition or assignment. A miss raises undeclared-entity. A dotted path such as 'historical_overage.has_overage' passes when its root is declared.

Literal values are not checked. That covers the right side of a comparison ('tier' is 'gold') and quoted phrases (say 'Thank you for calling').

The Simulate tab runs your parsed rules against a scenario. Set each declared variable and, optionally, type a user message. The engine walks the rules top to bottom:

• Conditions on declared variables are evaluated exactly (is, is not, greater than, at least, one of, and so on).
• Conditions in plain words (WHEN the user asks about refunds) are matched against the message by keyword and marked as such.
• Assignments that fire update the state, so later conditions see the new values.
• A fired rule whose verb routes (transfer, escalate, forward, select, …) and whose target names a registered agent adds a hop to the route. A prohibition on that route shows as blocked.

The simulation never changes the score.

Export AST downloads the parsed syntax tree as JSON or YAML for backend orchestration. The file holds the entity map, every node with its condition scope and action branches, all variable references, the diagnostics, and the current score. It is validated before download. The format is identified by schema: "syntaxforge/ast" and version: 1.

Every pattern below lives in grammar/literalness.yaml, with its points, its cap, and its wording. Edit the file and reload to add, remove, or retune a pattern; no code changes. The facet scores 100 − Σ min(cap, points × matches). Code fences, comments, notes, and tag lines are never scanned. The Builder runs the same patterns on every free-text field as you type.