Engine reference

How the engine works

Everything on this page is rendered from the engine's own data (RULES, DIMENSIONS, SEVERITY_PENALTY, STAGE_LABELS), so it cannot drift from the code.

Pipeline

Prompt parsing parse
Intent detection intent
Structure analysis structure
Requirement extraction requirements
Ambiguity detection ambiguity
Missing context detection missing_context
Instruction quality instruction_quality
Constraint analysis constraints
Output format analysis output_format
Token analysis tokens
Redundancy detection redundancy
Security & injection analysis security
Optimization strategy strategy
Prompt transformation transform
Validation validation
Quality evaluation evaluation
Token & cost comparison comparison

Stages 1–12 run for every analysis. Stages 13–17 run when you optimize. Only parsing can fail, and only for an empty prompt. Security findings are reported but never stop the pipeline.

Rule catalogue

Each rule links to a reference page with an example that triggers it, the engine's explanation, and a fixed version.

Code	Dimension	Fires when
`missing_objective`	Completeness	No task keyword, imperative sentence, or question.
`too_short`	Specificity	Fewer than 5 content words.
`vague_language`	Clarity	"something", "stuff", "etc", "and so on".
`unquantified_size`	Specificity	"short", "a few", "detailed" with no number.
`unclear_reference`	Completeness	"this" or "the above" with nothing included to refer to.
`missing_language`	Specificity	Code requested without a language or framework.
`hedged_instruction`	Clarity	"try to", "if possible", "maybe".
`long_sentence`	Clarity	A prose sentence over 40 words.
`negative_only_constraints`	Clarity	3+ prohibitions and no positive requirement.
`contradictory_instructions`	Consistency	Conflicting formats, lengths, word limits, tools, or languages.
`near_duplicate_instruction`	Consistency	Two sentences with ≥ 80% word overlap.
`missing_output_format`	Output specification	No output format named.
`missing_length_guidance`	Output specification	Content or summary task without a length limit.
`wall_of_text`	Structure	120+ words with no sections, lists, or breaks.
`duplicate_instruction`	Efficiency	A sentence repeated verbatim.
`filler_phrases`	Efficiency	Politeness and intensifiers that do not change the task.
`prompt_injection_signature`	Security	Weighted injection/jailbreak signature (critical at risk ≥ 60).
`sensitive_data`	Security	Credentials (critical) or personal data (warning).
`undelimited_variable`	Security	{{var}} or ${var} outside tags, fences, or triple quotes.
`destructive_operation`	Security	rm -rf /, DROP TABLE, delete all, curl \| sh.

Injection signatures version 2026.11.1. Signature matching reports risk, not proof: it can miss novel attacks and can flag text that quotes an attack to discuss it.

Scoring

Penalty per finding: critical 30, warning 10, info 3.
Overall = 100 − the sum of all penalties, clamped to 0–100, and capped at 50 if any finding is critical.
Each dimension = 100 − the penalties of the findings in that dimension. Structure applies only to prompts of 120+ words.
Grades: 85+ strong, 70–84 good, 50–69 needs work, under 50 weak.

Every report lists the checks that ran for each dimension and whether they passed, along with the evidence.

Transforms and modes

Mode	Transforms
conservative	Normalize whitespace; remove exact duplicate sentences.
balanced	+ Remove filler and politeness phrases (please, basically, leading I would like you to, greetings); in order to → to.
structured	+ Arrange sentences into Task, Context, Requirements, Output format, and Input sections; wrap template variables in tags.

Code blocks, inline code, quoted text, URLs, XML-tagged blocks, and template variables are protected: they are masked before any transform and restored byte for byte. No transform adds content except section headings and variable delimiters, and both are reported as changes.

Candidate verification

Each mode produces a candidate. A candidate is eligible only if:

every protected span is still present;
every original sentence is still present (after the same normalization the transforms apply);
every extracted requirement is still present;
it introduces no new warning or critical finding;
for conservative and balanced modes, it has no more tokens than the original.

The engine then selects by goal: tokens (fewest), quality (highest score), or balanced (highest score within 115% of the original's tokens). The original is always a candidate and wins when nothing is better.

Restructuring

restructurePrompt turns a loosely written request into a sectioned engineering prompt. It is a different operation from optimizing: optimizing removes words and proves nothing was lost; restructuring reorganizes, and for software tasks adds a test plan.

Clean. The same filler and duplicate removal as balanced mode.
Split. Run-on sentences are split into clauses at conjunctions that start a new instruction (fix X and make Y work and don't break Z). Verb pairs and noun lists are left alone.
Sort. Each clause goes to Role, Objective, Context, Requirements, Constraints, or Expected output. Code, quotes, URLs, and variables are never edited.
Scaffold. For software tasks only, fixed guidance is added by detected intent (debugging, new code, refactoring, testing, review, configuration, explanation) and topic (authentication, API, database, UI, performance, payments): edge cases, tests, acceptance criteria, and a default output format.

Every line in the result is labeled prompt (yours), engine (added guidance), or codebase (project facts supplied by the VS Code extension), so an interface can show exactly what was added. Sections with no content are omitted: a clear one-line request is returned unchanged, and a non-code prompt gets no test plan. Guidance you already gave is not repeated, and your own output format replaces the default. Pass scaffold: false to reorganize without adding anything.

The guidance is a fixed table in the engine source, not model output, so the same request always produces the same prompt. Section headings and guidance lines are in English.

Tokens and cost

OpenAI models are counted with o200k_base (or cl100k_base for GPT-4/3.5) and labeled exact. Other providers use o200k_base as a proxy and are labeled approximate. Without a loaded tokenizer, counts fall back to characters ÷ 4, labeled heuristic. Costs use a reference price table with the date each price was checked. See the model catalogue.