# Prompting and review

Canonical page: https://docs.ovok.com/working-with-ai-agents/prompting-and-review

## Give the agent enough context [#give-the-agent-enough-context]

“Build something with Ovok” leaves important decisions open. Describe the product workflow and the people who will use it. Include:

- **The user and their role:** for example, a patient recording a blood-pressure reading or a practitioner reviewing observations.
- **The workflow:** what starts it, what the user does, and what should happen next.
- **The data:** which clinical concepts, devices, or records are involved, and which system is authoritative.
- **Access rules:** who may create, read, update, or share each record.
- **The application:** its framework, existing authentication, and relevant repository conventions.
- **The environment:** whether the work is a code example, sandbox integration, or production change.
- **The expected result:** screens or API behavior to implement, plus how you will decide it is complete.

For example:

```text
Use the ovok skill. In this repository, add a practitioner view for reviewing a patient's recent blood-pressure observations.

First inspect the app structure and repository instructions. Then check the current Ovok docs for authentication, the relevant FHIR resources and search parameters, and any project setup required for this workflow. Use the existing app patterns. Keep tokens and patient data out of browser logs. Before coding, summarize the endpoint and access-policy assumptions; after coding, list the files changed and any Console setup an admin still needs to do. Use sandbox URLs in examples.
```

You can ask the agent to explain or plan a workflow before it edits files. For example: “Map this user journey to Ovok resources and endpoints. Show the required settings, features, access policies, and failure cases, and cite the docs you used. Do not change code yet.” This is useful when the data model or permissions need review first.

## Example prompts with the MCP server [#example-prompts-with-the-mcp-server]

With the [Ovok MCP server](/working-with-ai-agents/mcp-server) connected:

- **Set up a project:** “Read the project and its settings. Tell me which settings this app needs, and why, before changing anything. Then create a `default` client application named ‘Web app’ and tell me where to store its secret.”
- **Debug an app:** “Show the failed requests from the last hour. Pick the most common one, read its details, and explain the cause with the docs page that covers that route.”
- **Manage content:** “Read the CMS schema, then add German translations for the `onboarding` group as a draft. Show me the draft before publishing.”
- **Check usage:** “Read the plan and this month's usage, and tell me which allowance we will reach first.”

## A practical workflow [#a-practical-workflow]

For a feature that uses Ovok, work through these steps with the agent:

1. **Map the user journey.** Identify the actors, project, records, and actions. Decide what the patient, practitioner, and application can each do.
2. **Confirm the Ovok contract.** Have the agent find the exact docs for [authentication](/authentication), [Access policies](/access-policies), [settings and features](/settings-and-features), [FHIR basics](/fhir-basics), [FHIR R4 resources](/api/fhir/r4), [Ovok primitives](/primitives), [Slim APIs](/slim-apis), and [Data ingestion](/data-ingestion). If the implementation uses an SDK, have it check the documentation and declarations shipped with the SDK version in the project. Authorization should be designed early: confirm both the authenticated identity and the AccessPolicy requirements for each operation. Ask it to distinguish standard FHIR behavior from Ovok-specific operations and to verify request, response, and error details.
3. **Check project setup.** Identify required feature switches, settings, access policies, app URLs, and other prerequisites. With the MCP server connected, the agent can read them with `get_settings`. The skill warns about common configuration traps: for example, a feature-list `PATCH` replaces the complete list, an unset setting may behave differently from the value returned by `GET`, and a setting does not replace an access policy.
4. **Separate project setup from code.** Project creation and administration (settings, email templates, CMS content, billing, memberships, and access configuration) belong in the [OVOK Console](https://ovok.com/console?ref=docs), or to an agent through the [MCP tools](/working-with-ai-agents/mcp-tools). FHIR requests and application behavior belong in your application code through documented APIs or SDKs. Ask the agent to list setup steps separately from code changes.
5. **Implement against the existing application.** Keep patient and project scope explicit. Put credentials on the server where required. Use the sandbox for example requests and test data; do not put production tokens or real patient data in prompts, fixtures, or logs.
6. **Review the result.** Check changed files, FHIR version, query parameters, resource references, permissions, and error handling. Complete any setup, then exercise the workflow with appropriate test accounts before using it with patients. `get_failed_requests` shows what the app's calls got wrong.

## Review AI-generated changes [#review-ai-generated-changes]

<Callout type="warn" title="AI gets things wrong; review its output">

Agents are fast and often right, but they hallucinate fields, mix FHIR versions, and produce plausible-but-wrong code. Treat everything an agent writes as a draft to review, not a finished answer. Apply extra scrutiny to anything that affects security or data exposure, especially access policies, `ProjectMembership` scopes, and PHI handling.

</Callout>

Ask the agent to show the docs behind an endpoint or behavior it relies on. Review authorization and data access yourself, and test important cases, including unauthorized access, missing configuration, invalid input, and partial or failed writes. Do not treat a successful build as proof that a clinical workflow or permission model is correct.

The skill also asks agents to keep product claims precise: Ovok is not described as a certified medical-device platform, and the regulatory status of an application depends on its own intended purpose. For Signals behavior, verify the current [Signals documentation](/signals) and your product's requirements.