features optimizer coding brief

Coding Brief

Active contributors: ferdiiskandar

Purpose

The Coding Brief is the Optimizer's engineering output: an eight-section markdown brief the model writes, the engine validates against a deterministic contract (V1–V14), and repairs once if it fails. It is the default output kind for the CODING task type. Where the Super Prompt is free-form guidance, the Coding Brief is a checked artifact meant to be handed to a coding agent.

Key abstractions

Abstraction	Role	Source
runCodingBriefRoute	Generate, validate, repair, score quality	lib/optimizer/engine.ts
CODING_BRIEF_HEADINGS	The eight headings in fixed order	lib/optimizer/coding-brief-format.ts
CODING_BRIEF_REPORT_TEXT	Canonical REPORT body	lib/optimizer/coding-brief-format.ts
validateCodingBrief	Deterministic V1–V14 validator	lib/prompt-quality/contract.ts
deriveClarificationQuestions	At most three follow-up questions	lib/prompt-quality/clarification.ts

How it works

The eight headings are GOAL, CONTEXT, SCOPE, STACK, OUT OF SCOPE, DONE WHEN, ASSUMPTIONS, and REPORT. Seven are required (ASSUMPTIONS may be omitted when the user supplied everything). The model is told never to emit REPORT; the engine appends the canonical REPORT text itself with applyCanonicalReport, so the one invariant is that exactly one REPORT section exists and V8 can only fail on an engine bug, not on model output. The three v1.0 headings WHERE, SCENARIO, and FOLLOW PATTERN are still accepted and mapped to CONTEXT, SCOPE, and STACK, and are reported as deprecated rather than invalid.

The validator in lib/prompt-quality/contract.ts implements the rules. V1 checks structure: required headings, no duplicates, no unknown headings, and §4 order. V2 requires non-empty bodies. V3 caps GOAL at one sentence and 40 words. V4 requires CONTEXT to name a path, begin with New project:, or begin with Explore first:. V5 requires at least two SCOPE items. V6 and V7 require DONE WHEN to carry a backticked command or test identifier and not be only a vague outcome. V8 matches REPORT verbatim. V9 rejects lines that open with Optimizer settings labels. V10 checks that technologies named in the raw request appear in STACK. V11 marks a valid-but-thin brief. V12 rejects placeholder text that paraphrases the instruction. V13 rejects an unresolved [TODO: in a greenfield brief. V14 requires proposals the request did not state to be listed under ASSUMPTIONS. V10 and V14 run only when the raw request is passed in.

Greenfield versus brownfield decides how missing information is handled. A greenfield brief (CONTEXT begins with New project:) must propose everything and never leave a [TODO:; V13 enforces it. A brownfield brief may defer with Explore first: for CONTEXT and Propose a check first: for DONE WHEN, because only the repository can close those gaps. A brief where both defer is valid but thin (V11), never complete.

If validation fails, the engine makes exactly one repair call with the previous brief and the issue list, then validates again. attempts counts real provider calls: two with repair. The final quality verdict is complete, thin (valid but both openers defer), or degraded with reason parse_failed when no brief section parsed at all, or invalid_brief when it parsed but still fails. The engine then derives clarification questions from the delivered brief: a brownfield deferral first, then ASSUMPTIONS lines, never STACK. There is one round only, capped at three questions, and a refined brief offers no further questions.

stateDiagram-v2
  [*] --> Generate
  Generate --> Validate
  Validate --> Complete: valid, not thin
  Validate --> Thin: valid, both openers defer
  Validate --> Repair: invalid
  Repair --> Validate2
  Validate2 --> Complete2: valid
  Validate2 --> Degraded: still invalid
  Complete --> [*]
  Thin --> [*]
  Complete2 --> [*]
  Degraded --> [*]

Loading

Integration points

• The route uses buildCodingBriefSystemPrompt and buildCodingBriefUserPrompt; see Optimizer and LLM providers.
• The renderer shows clarification questions and sends answers back as a refinement; see Desktop console.

Entry points for modification

Change the headings, canonical REPORT, or technology lexicon in lib/optimizer/coding-brief-format.ts. Change rules in lib/prompt-quality/contract.ts. Change question selection in lib/prompt-quality/clarification.ts.

Key source files

File	Purpose
lib/optimizer/coding-brief-format.ts	Sections, canonical REPORT, lexicon, heuristics
lib/prompt-quality/contract.ts	V1–V14 validator
lib/prompt-quality/clarification.ts	Clarification questions
lib/optimizer/engine.ts	Generate, validate, repair, quality verdict