# Review Templates
URL: https://docs.clearly-ai.com/docs/review-templates
Description: Define Review questions and answer structure.
Review Templates define what Clearly AI asks and how answers are structured during a review. The exact catalog (names, frameworks, and question counts) is **different for every organization**; use the **Review Templates** area to see what yours includes.

**Who can use this**

* The sidebar shows **Review Templates** only when your account has permission to view them.
* **Editing** from the list uses a product feature flag. If you see **Download** and **Delete** but no **edit** action, ask an administrator whether the review template editor is enabled for your workspace.

**What you can do (when the editor is available)**

* See all current review templates in one table (filename, version, title, and question count).
* **Create** a new review template in the visual editor, or **upload** YAML files supplied by your team.
* Change question wording, structure (sections and headings), and many technical details of each **block** (question type, options, instructions to the model, and similar).
* **Download YAML** to back up or share a definition, then **upload** again to create a new version or a derivative review template.
* Run **tests** against real projects that already used this review template, so you can compare results before you rely on changes in production reviews.

<Callout title="YAML and advanced structure">
  Review Templates are stored as YAML with a defined shape (blocks, types, tables, and more). For field-by-field reference and examples, see [Review template schema](https://docs.clearly-ai.com/docs/review-templates/schema).
</Callout>

To author YAML outside the app, use [Clearly Quickstart](https://docs.clearly-ai.com/docs/clearly-quickstart). For starting points, see [Review template examples](https://docs.clearly-ai.com/docs/review-templates/examples).

***

## Open review template management [#open-review-template-management]

1. In the sidebar, click **Review Templates** (under **All Projects** when both are visible).
2. You will see **Review Template Management**: options to create visually, upload YAML, and a **Current Review Templates** list.

The **Current Review Templates** table shows **Filename**, **Version**, **Title**, **Questions** (count of blocks in the structure), and **Actions** (typically edit, download, and delete).

***

## Create a new review template (visual) [#create-a-new-review-template-visual]

1. Click **Create New Review Template Visually**. The app opens the editor for a new review template (often starting from an “untitled” draft).
2. Fill in **Title** (required) and optional **Description**.
3. Optionally expand **General Instructions** — text that guides the model across the whole review template.
4. Use &#x2A;*Add:** **Question**, **Text Section**, or **Summary Block** to build the outline. **Text Section** adds headings and narrative; **Question** adds an item the model must answer; **Summary Block** is for rollup-style content when your review template uses it.
5. Click **Create Review Template** (first save) or **Save Changes** (later). If the title would match an existing filename, the editor warns that saving will create a **new version** of that review template.

***

## Edit an existing review template [#edit-an-existing-review-template]

1. In **Current Review Templates**, use the **edit** control on the row for the file you want (opens `/review-templates/<filename>`).
2. Adjust metadata (**Title**, **Description**, **General Instructions**) the same way as for a new review template.
3. Expand a block to edit its fields. Depending on **block type** (for example free-form, single or multi select, table generation, aggregate risks, secrets scan), you will see different options — always including the main **question or prompt text**, and often **hidden instructions for the AI**, **options**, **assertions** (how compliance is evaluated), and an **answer strategy** preset.
4. Reorder blocks by dragging the **handle** on the row.
5. **Save Changes** when you are finished.
6. Use **Download YAML** if you want a file copy. **Upload Review Template** on the management page accepts that YAML; re-uploading the same filename creates a **new version** (existing reviews keep the version they were run with).

The page has no **Duplicate** button yet. To fork a review template, **Download YAML**, rename the file (the filename is the review template id), and **upload** the new file, or create a new visual review template and rebuild from your downloaded copy.

***

## Writing effective prompts [#writing-effective-prompts]

The text the model sees (the visible question plus any **hidden instructions**) drives answer quality. Short, vague prompts tend to yield vague or “not enough information” answers. Prefer concrete, testable language your sources can support.

| Too vague                 | More effective                                                                                                   |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| “Check authentication.”   | “List how each HTTP API validates callers (tokens, mTLS, etc.) and whether validation happens on every request.” |
| “Review data protection.” | “State how sensitive data is encrypted at rest and in transit, and where keys are stored relative to the data.”  |

***

## Making use of the Knowledge Base [#making-use-of-the-knowledge-base]

Files in the Knowledge Base are available at run time. To use a specific file in the Knowledge Base, reference it by name or title in the prompt or hidden instructions. To use the Knowledge Base more broadly, describe what information should be used from the Knowledge Base. Note that extremely large KB files or overly vague descriptions may get less useful results.

You can also explicitly instruct the LLM to exclude files in the Knowledge Base. For example, if you have specialized policies, you can instruct the LLM to use one policy and ignore another based on some criteria, such as geographical region, or sensitive data types.

***

## Test changes before reviews go live [#test-changes-before-reviews-go-live]

The editor can run **isolated tests** using projects that **already have reviews created with this review template**. If no such projects exist yet, complete at least one normal review first so there is source material to test against.

**Full Review Test**

* When projects appear in the **Full Review Test** panel, select one or more and click &#x2A;*Run Full Review (n)**. The run is tracked under **Test Runs**; select a run to inspect outputs inline with the review template.

**Test a single question (block)**

* While editing a **Question** block, use **Test on Projects** (when shown), pick projects, and run **Test Selected**. Results can show **Current Version** and **Edited Version** side by side so you can see the effect of your edits on the same sources.

This is **not** a generic “compare two different review templates” tool. It is aimed at validating **this** review template’s draft against real project data.

***

## Suggested structure for a new security review template [#suggested-structure-for-a-new-security-review-template]

If you are designing from scratch, grouping topics under **Text Section** headings helps reviewers scan results. One usable pattern:

| Section                 | What to cover                               |
| ----------------------- | ------------------------------------------- |
| Authentication & access | Identity, tokens, privilege boundaries      |
| Data protection         | Encryption, classification, retention       |
| Network exposure        | Ingress and egress, segmentation            |
| Input and dependencies  | Injection risks, third-party and OSS use    |
| Logging and operations  | Audit trails, monitoring, incident handling |

These text headings are not used as context when answering questions, they are purely for visual organization.

***

## YAML upload and versioning [#yaml-upload-and-versioning]

* On **Review Template Management*&#x2A;, drop or browse **.yaml*&#x2A; / **.yml** files, then **Upload**. Multiple files are supported; each file’s name (without extension) becomes the review template id.
* Uploading a file whose id already exists **creates a new version**; the UI reminds you that **existing reviews are not retroactively changed**.

***

## FAQs [#faqs]

<Accordions>
  <Accordion title="Why don’t I see Review Templates in the sidebar?">
    Your role may not include review template access; ask an admin.
  </Accordion>

  <Accordion title="Why can’t I edit from the review template list?">
    The review template editor feature may be off for your organization.
  </Accordion>

  <Accordion title="Why does an old review still look the same after I save edits?">
    Reviews are tied to the **review template version** from when they were created. Open that review and use **Regenerate** if you want to re-run against updated definitions, or start a **new** review so it picks up the latest version.
  </Accordion>

  <Accordion title="What should I do if I deleted a review template by mistake?">
    Deletion is permanent in the UI. Restore from a **Download YAML** copy if your team kept one, or re-upload a backup file.
  </Accordion>

  <Accordion title="Why is Full Review Test empty?">
    No project in the workspace has a review that used this review template yet; run a normal review first.
  </Accordion>
</Accordions>

***

## What’s next [#whats-next]

| Goal                        | Where to look                                                                                                                      |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Block types and YAML fields | [Review template schema](https://docs.clearly-ai.com/docs/review-templates/schema)                                                                            |
| Reviews                     | [Reviews](https://docs.clearly-ai.com/docs/reviews)                                                                                                           |
| Authoring YAML as code      | [Clearly Quickstart](https://docs.clearly-ai.com/docs/clearly-quickstart)                                                                                     |
| Example starting points     | [Review template examples](https://docs.clearly-ai.com/docs/review-templates/examples)                                                                        |
| Connecting source repos     | [GitHub](https://docs.clearly-ai.com/docs/integrations/code/github), [GitLab](https://docs.clearly-ai.com/docs/integrations/code/gitlab), [Bitbucket](https://docs.clearly-ai.com/docs/integrations/code/bitbucket) |