Opti'The principle, in one sentence
The model proposes, fixed rules check, and you decide. A language model can propose relevant questions for a post-distribution monitoring survey or a baseline study. It is not reliable for what makes an XLSForm work: unique variable names, conditions that refer to questions that exist, formulas ODK can run. A mistake on these points does not show on screen; it is found at deployment, or in the field, in front of an enumerator.
So the method separates the two. The model works on the content. Everything to do with structure goes through written rules, tested and identical every time: a formula compiler, name checks, a workbook audit, then validation by the very tools KoboToolbox uses.
In practice: if a display condition says
${received_aid} = 'yes', it does not go into the file because the model wrote it. It goes in because received_aid exists, because yes is one of its options, and because the expression was compiled.
Four ways to build, four roles for AI
The XLSForm Builder in Opti Gemba accepts four starting points. Artificial intelligence does not play the same role in each, and that is deliberate: the more your document says, the less the model has to decide.
| Starting point | What AI does | What it does not do |
|---|---|---|
| Describe the survey | Proposes a section plan, then the questions, options, conditions and calculations. | Decide the languages or the topic for you: they come from your request. |
| Ask for a change | Applies what you point to: "make this question required", "add a constraint". | Touch the rest of the questionnaire. Every change can be undone. |
| Import a Word or PDF file | Fills in what the document does not say: a missing question type, a missing translation. | Reword a question, invent an option code, add a question that is not written. |
| Import an XLSForm, type by hand | Nothing. | Syntax checks and ODK validation still apply. |
The stages of a generation
A full questionnaire does not come out of a single call to a model. It is built in stages, each of which answers a specific risk. You see the plan before a single question is written, and the questionnaire fills in before your eyes, section by section.
| Stage | What happens | The risk it covers |
|---|---|---|
| 1. Framing | The topic, the survey type and the languages are taken from your request. An informed consent text is prepared in each language. | A questionnaire in the wrong language, or without consent. |
| 2. Plan | Sections are proposed and shown, with their estimated number of questions. The cost is estimated on this plan, before generation. | An off-topic questionnaire, found out once paid for. |
| 3. Design | For each section, the model proposes the questions, their types and their dependencies. | A single block where one error spreads everywhere. |
| 4. Enrichment | In batches of ten questions: options, constraints, instructions. | A truncated response that loses questions. |
| 5. Build | Without a model: variable names, de-duplicated choice lists, required status, appearance. | Duplicate names, three lists for the same scale. |
| 6. Conditions | A dedicated pass writes or repairs display conditions. If the target option does not exist, the condition is removed rather than guessed. | A question that shows for everyone, or for no one. |
| 7. Calculations | Scores and indicators are described as a structure, checked arithmetically, then compiled. | A wrong composite index with nothing to flag it. |
| 8. Translation | The questionnaire is written in one working language, then the other language columns are filled in. A cell already filled is never rewritten. | A reviewed, sometimes contractual, translation overwritten by a machine translation. |
| 9. Verification | Workbook audit, then real ODK validation before export or sending to Kobo. | A file rejected at the last step, or worse, accepted and wrong. |
A generation interrupted for lack of balance or network keeps the sections already produced and resumes at the next one, without paying for the plan again.
Import: the document is the authority
Many questionnaires already exist in Word or PDF, sometimes approved by a donor or an ethics committee. Having AI rewrite them would be a risk; retyping them, a waste of time. So the rule is simple: the document dictates, the model only fills the gaps.
- A specification table is read without AI. When the header says "variable name, question, type, required, options, condition", each row is transcribed as is, without using a single token.
- Nothing is lost on the way. The number of questions read is compared with the number produced; if they differ, the batch is split down to the single question. A question is never dropped.
- Written skips are rebuilt, and only those. "If yes, go to Q10" becomes a condition; an ambiguous instruction does not.
- The author's names are kept. If one has to change for ODK to accept it, the mapping is kept: you can go on writing "add a constraint on HH_size".
- What Opti' adds is flagged. An "Other" option with no "Specify" question after it would lose the real answer: the question is added, and the addition appears in the import notes.
Every import ends with a report: what was transcribed as is, what was filled in, and what could not be established. That is where you learn it, not in the field.
What the model decides, what the rules decide
The line is clear, and it is what makes the file reliable.
Proposed by the model, reviewed by you
- The section plan and the questions.
- The answer options and instructions.
- The intent of a condition or a calculation.
- The consent text and the translations.
Decided by fixed rules
- Variable names and their uniqueness.
- The syntax of every formula, compiled.
- Choice lists, de-duplicated.
- Group consistency, and acceptance by ODK.
The checks, one by one
No formula leaves without being compiled
Conditions, constraints, calculations, choice filters: every expression is parsed, checked and rewritten by a compiler. What can be repaired mechanically is, without calling the model. What cannot is removed and flagged, never delivered broken.
A name that does not exist is refused, never guessed
A formula that refers to a variable missing from the questionnaire is not linked to the "closest" variable. Guessing, here, means producing a skip that looks right and is not.
Variable names are compliant, and their references follow
A variable name becomes an XML element: it cannot start with a digit, which trips up many numbered questionnaires. Renaming it is not enough, since it is referred to elsewhere; every rename therefore also rewrites all references, in formulas and even in labels.
Scores are checked by calculation
For a composite index (food consumption score, rCSI, Likert scale), the number of items multiplied by the maximum score is compared with the divisor written by the author: 33 items scored out of 4 give 132. If not, Opti' says which number does not add up. A scale with text options is renumbered so the sum can be computed in ODK, without touching the labels.
A workbook audit, before anything is sent
Four families of errors can be read straight from the file: a duplicate option, a reference to a question that does not exist, an empty group, a missing choice list. This audit runs in your browser, offline, for free. When it finds nothing, it says "nothing to report here", not "valid questionnaire": that would be inaccurate.
Validation with Kobo's own tools
KoboToolbox validates a questionnaire in two steps, and the second, which runs pyxform and ODK Validate, only happens at deployment. A file can therefore be imported without error and rejected at the last step. Opti' submits the file to that same pair of tools before export or sending to your KoboToolbox account.
Fix, re-check, repeat
ODK only reports the first error it meets. Every fix is therefore followed by a new check. Purely technical fixes are applied automatically and announced; those that touch your names or options are proposed to you, precisely, and you approve them in one click. The loop stops by itself if it makes no progress. And an unreachable validation service is never presented as a rejection: it blocks nothing.
What the model is not allowed to do
- Invent a variable name in a formula, or link a broken reference to a name that looks like it.
- Invent an option code. A code used in a condition must exist in the question's list.
- Rewrite an imported question. The document's wording is copied as is.
- Overwrite an existing translation. Only empty cells are filled in.
- Deliver a formula that does not compile. It is repaired, or removed and flagged.
- Decide that a sensitive question is optional. That is a methodological choice that is yours to make, not something to guess.
The limits, stated plainly
A method that does not state its limits is hiding one. Here are ours.
- A file ODK accepts is not a good questionnaire. Validation guarantees it works, not that it asks the right questions.
- Generated wording can be leading or ill-suited to the cultural context. It reflects common sector practice, not your field.
- Machine translations need review. By a speaker of the language, ideally an enumerator.
- The generated consent is generic. It follows the usual structure (organisation, voluntary nature, confidentiality, duration, right to stop): adapt it to your organisation and your survey.
- By default, questions are required, sensitive ones included, unless your document says otherwise. Add a "prefer not to answer" option where it is needed.
- A scanned PDF reads less well than a Word file. Read the import notes before you go.
Review and testing
A generated questionnaire is a good draft, not a validated instrument. Before collection, the preview shows it exactly as respondents will see it, and can be filled in to test skips, constraints and length. A fix spotted during the test is made on the spot. Then comes the pilot test, in the field, which nothing replaces.
The points to check do not change because AI helped: consent first, suitable language, neutral wording, skips tested on several scenarios, exhaustive choice lists, planned disaggregations, scores checked on a known case, reasonable length. Definitions and basic syntax are on the page What is an XLSForm.
The SAFE AI Transparency Card
The SAFE AI framework, published in 2026 for humanitarian AI, asks that every use of AI be recorded in a Transparency Card. For a Tier 1 use, such as designing a questionnaire the team reviews, that is the Lean version. We have pre-filled it for the XLSForm Builder.
SAFE AI Transparency Card, pre-filled for the XLSForm Builder
The six sections of the Lean card from the SAFE AI Tools & Guidance v1.1. Opti' describes what it knows about its tool; your organisation completes what only it knows, then signs it.
- Pre-filled by Opti': models and suppliers, data used, safeguards, known limitations, model adaptation.
- Proposed, to confirm: the answers to the six red lines, each with its rationale.
- For you to complete, highlighted in yellow: context, accountable people, monitoring, decisions.
The card also says when it is no longer enough: if a generated questionnaire were fielded without human review, the use would change tier. For the narrative report, an equivalent card comes with the report methodology.
Your data
The generator only sees the questionnaire: your request, the current structure and, on import, the uploaded document. Respondents' answers are never sent to it. The models used are Mistral AI's, hosted in the European Union; no data is used to train a model. The details, processors included, are on the page Ethical AI and data protection.
Frequently asked questions
Are the questions written by artificial intelligence?
When you describe a survey, yes: the model proposes the questions and options, section by section, and you review them. When you import a questionnaire written in Word or PDF, no: your document's text is copied as is, and the model only fills in what the document does not say. Syntax is never left to the model: variable names, formulas and structure go through fixed rules.
Will the questionnaire pass on KoboToolbox?
Before any export or sending to Kobo, Opti' submits the file to the same pair of tools Kobo runs at deployment, pyxform and ODK Validate. A rejection is turned into a fix: applied automatically if purely technical, proposed for approval if it touches your names or options, then the file is checked again. If the validation service is unreachable, nothing is blocked and Opti' says so.
Can Opti' change the questions in my document?
No. On import, the wording is copied as is, the option codes and variable names written by the author are kept, and translations already present are never overwritten. When Opti' adds something, for example a "Specify" question after an "Other" option, the addition is flagged in the import notes.
How are scores and indices calculated?
The model describes the score as a structure (the items, the score for each answer, the weighting, the aggregation), and that structure is checked arithmetically before being compiled into a formula. If the number of items multiplied by the maximum score does not match the written divisor, Opti' says which number does not add up, instead of delivering a wrong index.
Do my collected responses go through the generator?
No. The generator only sees the questionnaire: your request, the current structure and, on import, the uploaded document. Respondents' answers are never sent to it.
What is the transparency card offered on this page?
It is the Lean Transparency Card of the SAFE AI framework, pre-filled by Opti' for the XLSForm Builder, in Word format. Opti' describes its tool, its data, its safeguards and its limitations; your organisation completes the context, the accountable people and the decisions, then signs it.
Where this happens in Opti'
Opti Gemba
The questionnaire, collection, analysis and report, in one MEAL mission.
Learn more →
Connect KoboToolbox
Send the questionnaire to Kobo in one click, and bring the responses back.
Learn more →
Report methodology
The same transparency for the narrative report: what is computed, what is written.
Learn more →