# Clearly Quickstart
URL: https://docs.clearly-ai.com/docs/clearly-quickstart
Description: Use the Clearly Quickstart repo to write and validate review template YAML with AI coding assistants.
Clearly Quickstart is a private repository for authoring review template YAML outside the Clearly AI web app.

Use it when you want to manage review templates as code, edit in Cursor or another coding assistant, and upload finished YAML into Clearly AI.

Ask your Clearly AI contact for repository access before following the steps below.

## What is in the repo [#what-is-in-the-repo]

The repo includes:

* `questionnaires/schema-questionnaire-v1.json`: JSON Schema for review template YAML.
* `questionnaires/questionnaire-blocks-reference.yaml`: commented examples of supported block types.
* `questionnaires/stride-tm.yaml`: a working STRIDE threat model example.
* `.agents/commands/create-questionnaire.md`: instructions for AI-assisted review template authoring.
* `questionnaires/tests/test_questionnaires.py`: tests that validate review template files.

Repository: [Clearly-AI/clearly-quickstart](https://github.com/Clearly-AI/clearly-quickstart) (private)

## Create a review template [#create-a-review-template]

1. Ask Clearly AI for access to the private quickstart repo.
2. Clone the repo after access is granted.
3. Open it in Cursor or your editor.
4. Start from `questionnaires/stride-tm.yaml` or `questionnaires/questionnaire-blocks-reference.yaml`.
5. Save your new review template under `questionnaires/`.
6. Validate it before upload.

```bash
uv run pytest
```

Then upload the YAML in Clearly AI from **Review Templates > Upload Review Template**.

## Author with an AI assistant [#author-with-an-ai-assistant]

The repo includes `.agents/commands/create-questionnaire.md`. Use it as the instruction file when asking an AI coding assistant to create or revise a review template.

Good input looks like this:

```text
Create a review template that classifies a project by production exposure, internet exposure,
personal data handling, authentication model, and required follow-up review.
Use single-select fields where the output should drive workflow branching.
Use freeform fields only for evidence summaries.
```

After generation:

1. Review the YAML yourself.
2. Run `uv run pytest`.
3. Upload the file to Clearly AI.
4. Run a test review against a project with representative sources.

## What to include [#what-to-include]

Every review template needs:

```yaml
metadata:
  title: "Review template title"
  description: "What this review is for"

blocks:
  - text: "## Section"
  - prompt: "Question the AI should answer."
```

Use:

* `text` for headings and reviewer guidance.
* `prompt` for freeform answers.
* `options` for single-select answers.
* `multi_options` for multi-select answers.
* `hidden_instructions` when the answering engine needs private guidance.
* `assert_any`, `assert_all`, or `assert_fuzzy` when you want pass/fail status.
* `aggregate_risks` when option-level risk scores should roll up.
* `summarize` as the final block when you need a generated summary.

See [Review template schema](https://docs.clearly-ai.com/docs/review-templates/schema) for field details.

## Upload and versioning [#upload-and-versioning]

The uploaded filename becomes the review template identifier. Uploading a file with the same identifier creates a new version. Existing reviews keep the review template version they were run with.

To fork a review template, change the filename before upload.

## Common mistakes [#common-mistakes]

**YAML turns `NO` into `false`.** Quote values such as `"NO"`.

**The summary block is not last.** Move `summarize` to the end. A review template can have at most one.

**The model guesses.** Tighten the prompt, add hidden instructions, or add better project sources and Knowledge Base context.

**A workflow needs structured branching.** Use single-select or multi-select questions instead of freeform prompts.