> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getvirtualbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompting Best Practices

> The standard five-part prompt template, the ten rules that matter most, a complete worked example, and how to build quality-control checks into a block

A block prompt is where your methodology becomes instructions the Mainframe can follow. Get the structure right and your Apps stay readable, maintainable, and predictable across every run.

## The standard prompt template

Every block prompt follows the same five-part scaffold.

```text theme={null}
Role & Context: [Role + domain, one sentence. "You are a senior X specialized in Y."]

Tasks:
1. [Verb + object. Reference inline variables in quotes: 'Using "rfp_summary", extract...']
2. [One action per line.]
3. [...]

Output format: [Exact structure: headers, table columns, section order.
Include one concrete example if the format is non-obvious.]

Constraints: [Optional. Terminology, scope, length, language.]

Inputs:
[VARIABLE NAME]: /variable_1
[VARIABLE NAME]: /variable_2
```

The Inputs section lists inline variables only: Free Text, Multiple Choice, and upstream outputs routed inline. Knowledge Sources (uploads, Brains, KS-routed outputs) are attached at block level and never appear in this list.

## The ten rules that matter most

These come from VirtualBrain's own deployment experience across customer Apps, not from published benchmarks.

<Steps>
  <Step title="Open with a specific role">
    "You are a senior M\&A analyst specialized in due diligence" consistently outperforms "Please help me with...". The role sets vocabulary, depth, and judgment.
  </Step>

  <Step title="One objective per block">
    If you write "and then..." in a prompt, split the block. Two objectives in one prompt degrade both.
  </Step>

  <Step title="Instructions before data">
    Put Tasks above large variable injections: the Mainframe retains instructions better when it reads them first.
  </Step>

  <Step title="Numbered tasks, verb-first">
    "1. Extract X. 2. Classify each item. 3. Score against the rubric." Enumerated flows are followed far more reliably than prose.
  </Step>

  <Step title="Keep prompts short">
    Target under 200 words, hard max 400. A 200-word prompt is followed more precisely than a 600-word one: long context is for data, not instructions.
  </Step>

  <Step title="Positive framing only">
    "Use only the terminology defined in the glossary" beats "don't use informal language". Tell the Mainframe what to do; negative instructions bloat prompts and underperform.
  </Step>

  <Step title="Say it once">
    Drop "be sure to...", "remember that...", "double-check...". One clear instruction beats three nervous repetitions.
  </Step>

  <Step title="Embed domain terms verbatim">
    Scoring scales, business rules, thresholds, and frameworks go into the prompt exactly as the business defines them. Paraphrasing domain language creates drift.
  </Step>

  <Step title="Use the Mainframe's judgment for evaluation">
    "Apply your judgment to resolve conflicts between criterion A and B; briefly explain the trade-off" beats a brittle hard-coded decision tree.
  </Step>

  <Step title="Quote variables in tasks">
    'Using the context in "context\_notes", prioritize...' the explicit reference connects the instruction to the data.
  </Step>
</Steps>

<Tip>
  The platform [prompting coach](/apps-academy/prototyping) reviews any block prompt against these rules and suggests a sharper role, clearer tasks, or a tighter output format. Reach for it whenever a block underperforms.
</Tip>

## A complete example prompt

```text theme={null}
Context: You are a senior recruitment analyst specialized in technical hiring.

Tasks:
1. Using the requirements in "job_requirements", search the candidate
   database for skills, certifications and experience that match.
2. Score each candidate on a 1-5 scale per criterion: technical skills,
   seniority, industry fit.
3. Rank candidates by total score and flag any disqualifying gap.

Output format:
## Candidate Shortlist
| Rank | Candidate | Technical (1-5) | Seniority (1-5) | Fit (1-5) | Total | Flags |
One row per candidate, ordered by Total descending.
## Recommendation
3-5 sentences naming the top candidate and the decisive criterion.

Constraints: Evaluate only against the stated requirements.

Inputs:
JOB REQUIREMENTS: /job_requirements
EVALUATION DEPTH: /evaluation_depth
```

<Note>
  What is not here: the candidate database (a Knowledge Source) is attached at block level and never listed under Inputs. The prompt instead tells the retrieval what to look for.
</Note>

## Build in quality-control checks

For high-stakes or calculation-heavy work, do not trust a single pass. Three techniques catch the most common failures before the user ever sees them.

* **Add validation instructions inside the prompt.** Ask the block to verify its own work before producing the output, for example "recompute every total and confirm the columns add up", "flag any two data points that contradict each other", or "if a figure is missing or implausible, mark it rather than guessing". Each takes one line and catches the most common failures.
* **Use a dedicated quality-control block.** Add a Hidden block whose only objective is to audit the previous block's output: reconcile figures, surface inconsistencies, confirm every required section is present, and pass a short note plus any corrections downstream. Keep checking separate from producing: one block does the work, the next checks it.
* **Make the check show its reconciliation.** When numbers matter, have the check state what it verified ("totals match source: yes; dates consistent: yes; 1 outlier flagged") so a reviewer can trust the output at a glance.

<Tip>
  A checking standard every App in the firm should meet belongs in [Company Context](/features/personalization/custom-instructions), which every App run carries. Personal **My Instructions** never reach an App, so anything this workflow must always check belongs in the block's own instructions. See [App Blocks](/features/apps/app-blocks) for how Hidden blocks fit into the pipeline.
</Tip>

## Next

<CardGroup cols={1}>
  <Card title="Controlling the Output Format" icon="table-cells" href="/apps-academy/output-format">
    Engineer the same recognizable layout on every run.
  </Card>
</CardGroup>