features optimizer super prompt

Super Prompt

Active contributors: ferdiiskandar

Purpose

The Super Prompt is the Optimizer's general-purpose output: a six-section markdown prompt the model writes and the engine parses into a typed SuperPrompt. It is the default output kind for every task type except CODING.

Key abstractions

Abstraction	Role	Source
parseSuperPromptMarkdown	Splits ## HEADING sections, builds SuperPrompt	lib/optimizer/super-prompt-format.ts
parseSuperPromptJson	Parses a JSON response into the same shape	lib/optimizer/super-prompt-format.ts
SuperPromptWireSchema	Tolerant-but-strict wire guard	lib/optimizer/super-prompt-format.ts
PromptQualitySchema	Canonical SSOT guard	lib/prompt-quality/contract.ts
buildOptimizeUserPrompt	Per-idea quality routing guidance	lib/llm/prompt-builder.ts

How it works

The format is fixed by the system prompt. The headings, in order, are ## ROLE, ## TASK, ## CONTEXT, ## APPROACH, ## CONSTRAINTS, and ## OUTPUT FORMAT. APPROACH is optional to parse; the other five are required. The system prompt tells the model to output markdown only, with no fences, no preamble, and no trailing commentary, and that APPROACH must stay high-level rather than reveal hidden chain-of-thought.

Two parsers read the response. parseSuperPromptMarkdown strips an outer fence, scans uppercase ## HEADING lines, checks for the required headings, extracts CONSTRAINTS bullet lines, maps APPROACH to chainOfThought, and guards the result with PromptQualitySchema. parseSuperPromptJson handles a JSON payload, unwraps a fenced block if present, validates against SuperPromptWireSchema, and assembles fullPrompt from the fields when it is absent.

The two guards do different jobs. SuperPromptWireSchema is tolerant about presence but strict about types: every field is .nullish(), so a missing or explicitly-null field is fine, but a wrong type such as constraints: "x" or role: 5 fails and throws. Tolerance never comes from coercion, so malformed output still routes to the engine fallback rather than being silently repaired. PromptQualitySchema is the canonical contract (SuperPromptSchema) and is the final gate: a parsed candidate either conforms or throws, which triggers the engine's parse_failed fallback.

The user prompt carries quality routing guidance built by buildQualityRoutingGuidance. It states the preferred instruction language, requires exactly one explicit output-length constraint, keeps the user's wording and deliverable framing close to the original, preserves a named audience and any requested headings, and avoids adding scaffolding the user did not ask for. Operator-heavy tasks additionally get a note to preserve numbers, units, and named entities verbatim.

Integration points

• The engine calls either parser after the provider responds; see Optimizer.
• PromptQualitySchema is the same SSOT the Coding Brief validator imports; see Coding Brief.

Entry points for modification

Change the required headings and section mapping in lib/optimizer/super-prompt-format.ts. Change model instructions in lib/llm/prompt-builder.ts. The canonical field set lives in lib/prompt-quality/contract.ts.

Key source files

File	Purpose
lib/optimizer/super-prompt-format.ts	Markdown and JSON parsers, wire schema
lib/prompt-quality/contract.ts	PromptQualitySchema SSOT
lib/llm/prompt-builder.ts	System prompt and quality routing guidance