Why we do this
A document analysis is only as good as the context the AI has. For some document types — e.g. an employment warning letter — a single piece of information decides whether the analysis hits the mark or misses it:
- Are you the employee (you received the warning) or the employer (you are reviewing your own draft)?
- Were there earlier reprimands or warnings?
- Was a hearing held before it was issued?
- Is a dismissal already on the table?
Without these answers, the AI has to guess. With them, it delivers an analysis tailored precisely to your role and risk position — deadline, right of rebuttal, a pointer to the time limit for an unfair-dismissal claim (which varies from country to country).
How it works: three trigger points
- Level 1 — recommendation before the analysis: For curated document types (e.g. a warning letter, a dismissal, a termination agreement), a dialog opens after upload with two equally weighted buttons: Yes, ask clarifying questions ({price}/round) or Analyse directly. Nothing is pre-selected — you decide actively.
- Level 2 — override during the analysis: Even when no standard clarifier is recommended, you will see a discreet link during the running analysis: "Add context for a better analysis?". A click opens the same dialog with 2–3 freely worded context questions.
- Level 3 — refine after the analysis: Below the result, the "Add clarifying questions" button appears. You answer 1–3 questions aimed specifically at gaps in the existing analysis — after which the analysis is updated.
All three routes use the same payment mechanism (analysis_clarify_gather, default 1 credit/round, max. 3 rounds). Each round shows the exact price before the charge. Your answers land as a clearly marked note block in the final analysis prompt, and caching is automatically disabled.
What runs under the hood
- Model: google/gemini-2.5-flash-lite — fast and low-cost, because it only has to formulate questions, not run the analysis.
- Token budget: 800 output tokens, temperature 0.2 — crisp questions, no essays.
- Safety net: a refund on every failed call, a daily-limit check before every round.
- Per-playbook control: which document types trigger Level 1 is decided by the editorial team in the admin area (Playbooks → "Pre-analysis clarification active" toggle + rationale + slot hints). For each playbook, the "Allow override" toggle also controls whether Level 2 and 3 are available for that document. Default: allowed.
- Fallback path: For documents without a matching playbook, the system allows Level 2 and 3 by default — the AI then formulates 2–3 open context questions that are genuinely decisive for an accurate analysis.
- Global kill switch: the analysis_clarify_enabled feature flag (with max_gather_turns) — in case the feature ever has to be paused.
What it is not
- No compulsion. If you already know the document and the answers are in the text anyway, skip the dialog.
- No hidden surcharge. The clarification step is its own line item in your credit history — reason code analysis_clarify_gather.
- No substitute for a lawyer. The clarifying questions sharpen the context for the AI analysis. For the deadline of your dismissal-protection claim, a specialist lawyer remains your first choice.
In parallel: clarifying questions when drafting a document
You have had the same mechanism for a while now in the Schreib-Assistent (reason code writing_intake_gather): when you generate a document without a template — e.g. a warning letter as an employer — the AI asks targeted clarifying questions about the facts, the evidence and the desired sharpness of tone before the finished document is produced. There too: every round priced visibly, skippable at any time.
Where you can already see it today
- Vault → upload a document → "Analyse" — with an active playbook the dialog appears automatically.
- During any analysis: the discreet "Add context" link — even without an active playbook.
- After any analysis: the "Add clarifying questions" button in the actions footer.
Playbooks enabled by default (as of today): Employment warning letter (DE/AT/CH), Review termination agreement (DE), Review employment reference (DE), Employee dismissal (DE), Employment dismissal (AT/CH), Rent reduction (DE/AT), Building-permit refusal (DE), Lawyer's letter/demand (DE/AT/CH).
More playbooks will follow. Suggestions on where clarifying questions would make the difference? Please use the feedback thumbs right on the result.
