# Chat AI Mode

The **AI Chat Mode** is where you describe what you want. The AI turns that into **specification**, **code**, and an app running on the **Preview**.

Use Chat AI to:

* Create an app from scratch.
* Make large changes (new modules, entities, screens).
* Iterate quickly with approval at each step.

{% hint style="info" %}
For “surgical” backend changes, use the [Editor Mode](/documentation/editor-mode.md).
{% endhint %}

### Prerequisites

* You have edit permission on the project.
* Your app opens in the **Preview**.

### Typical flow

{% stepper %}
{% step %}

### Write a prompt (intent + constraints)

Include:

* App goal.
* Modules and entities.
* Fields and types (e.g., `String`, `Date`, `Picklist`).
* Business rules (validations, states, permissions).

{% hint style="warning" %}
Avoid asking for “everything at once”. Break into changes of 1–3 items.
{% endhint %}
{% endstep %}

{% step %}

### Review the app specification

The analyst agent proposes a **App Specification**.

Review focusing on:

* Names of modules, entities and fields.
* Relationships (1-N, N-N) and required fields.
* Rules that need to become validations.
* What stays **out of scope**.

If something is wrong, correct it in the chat with clear instructions.
{% endstep %}

{% step %}

### Approve and follow the agentic coding

Upon approval, the agents begin generation.

You should:

* Wait for completion.
* Read the summary of what was changed.
* Validate whether the intent was met.
  {% endstep %}

{% step %}

### Test in Preview

Use Preview to validate the actual flow.

Quick checklist:

* Navigation (menus, routes).
* Basic CRUD (create/edit/list/remove).
* Business rules and validations.
* Perceived performance (lists, filters).
  {% endstep %}

{% step %}

### Make “Change Requests”

When you request an enhancement, the AI opens a **change request**.

Best practices:

* Write atomic changes.
* State what should change and what should remain.
* State how to validate: “expected result”.

Prompt examples:

* “Add a **attachments** in **Task**. Type attachments.”
* “Create the module **Projects** and relate **Task → Project** (1 project per task).”
* “Create a picklist **status** with: New | In Progress | Review | Done.”
  {% endstep %}
  {% endstepper %}

### Quick prompt tips

* Prefer imperative phrases: “create”, “add”, “change”, “remove”.
* Name entities and fields consistently.
* Always state the impact on screens: list, form, detail.
* When there is a rule: describe the **trigger** and the **expected error**.

### If something goes wrong

* If generation stalls or becomes inconsistent: see [AI generation failures](/troubleshooting/ai-generation-failures.md).
* If Preview doesn’t open: check extensions (adblock) and try an incognito window.

### Recommended readings

* First project in 15 min: [Start here](/get-started-here.md)
* How to write better prompts: [1. Prompt tips](/hands-on-tutorials/1.-prompt-tips.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.madrix.dev/documentation/chat-ai-mode.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.