Single "Enhance with AI" action and purpose-focused report content prompt

[steilerDev]

[product-owner]

As a homeowner writing a report for a bank, I want one obvious "Enhance with AI" action that produces text explaining why each cost was incurred so that I do not have to opt in twice, and the generated prose adds information the table does not already show.

Priority: Should Have
Parent Epic: none — part of the parent-less Bank Report Wizard cluster (#1876–#1879, #1898–#1901, #1923–#1925).
Found during: user review of the AI feature shipped in #1901 (2026-08-01).

Problem

Two separate defects, one UX and one content-quality, both in the AI assistance path added by #1901.

1. Double opt-in

client/src/pages/ReportWizardPage/Step4Settings.tsx L~108–125 renders an "Enable AI assistance" checkbox (only when llmEnabled), which sets aiEnabled. client/src/pages/ReportWizardPage/ReportWizardPage.tsx L860 then gates the step-5 action on aiEnabled:

{aiEnabled && (
  <div className={styles.aiGenerateRow}>
    <button ... onClick={handleGenerateWithAiClick} ...>
      {t('sourceReports.editable.generateWithAi')}   // "Generate with AI" / "Mit KI generieren"

The toggle carries no state of its own — it exists purely to reveal a button that the user must then also click. The user must opt in twice to do one thing, and there is no way to discover the feature from step 5 if the toggle was left off. llmEnabled (from GET /api/config) already tells us whether the capability exists; the toggle adds nothing.

The label is also wrong for what the action does. It runs against content that already exists (the deterministic table and cover letter are built before AI is ever invoked, and the AI result overwrites them — hence the "overwrite your edits?" confirmation in handleGenerateWithAiClick, L595). The action improves existing content; it does not generate content from nothing.

2. The generated text restates the table

REPORT_CONTENT_SYSTEM_PROMPT (server/src/services/budgetExtraction/prompts.ts L133) asks for "one-line factual descriptions for invoices" and "a collective summary of work completed", and buildReportContentUserPrompt (L149) feeds the model vendor, invoice number, date, amount, notes and budget-line descriptions.

The model therefore writes back what it was given — the what. But the vendor, the invoice number, the date and the amount are already columns in the very same table row, and the linked item name is often the budget-line description verbatim. The Usage column ends up as a redundant restatement, consuming page width (see the PDF-layout issue in this batch) without adding information a bank reader can use.

What a bank reader cannot see, and what the homeowner actually needs to convey, is why the cost was incurred — what role that purchase or service played in the construction project.

3. Length caps disagree between the prompt and the validator

Field	Prompt states	Validator enforces
letterSubject	max 150 (prompts.ts L140, L193)	truncate at 200 (openAICompatibleProvider.ts L330)
letterBody	max 2000 (L141, L194)	truncate at 3000 (L337)
description (per invoice)	max 200 (L139, L195)	truncate at 300 (L367)

The model is instructed to one limit and silently permitted a wider one, so overlong output passes through unclipped and lands in a table cell sized for something shorter.

Acceptance Criteria

Settings step

• 1.1 Given the report wizard's step 4 (Settings), When the step renders with an LLM configured, Then there is no "Enable AI assistance" control of any kind — the whole AI-assistance section is gone.
• 1.2 Given step 4 after the change, When the step renders, Then the report-language, attach-documents, and include-cover-letter controls behave exactly as before, including the cover-letter disabled hint.
• 1.3 The aiEnabled state and its prop plumbing are removed, and the now-unused sourceReports.settingsStep.enableAiAssistance / enableAiAssistanceHelper keys are removed from both en and de locale files (no orphan keys, no missing keys).

Step 5 action

• 2.1 Given an instance where the LLM is configured (llmEnabled: true from GET /api/config), When step 5 renders, Then exactly one AI action button is present, with no prior opt-in required.
• 2.2 Given an instance where the LLM is not configured (llmEnabled: false), When step 5 renders, Then no AI action button, spinner, note, or error slot is rendered anywhere in the step.
• 2.3 Given the AI action button, When it renders, Then its label reads "Enhance with AI" in English and an equivalent in German that uses "KI" for AI, consistent with the existing de copy in this namespace.
• 2.4 Given the user has edited one or more fields in the step-5 editor, When the AI action is clicked, Then the existing overwrite confirmation still appears before any request is made (no regression to handleGenerateWithAiClick).
• 2.5 Given the AI action is in flight, When the user observes step 5, Then the existing loading spinner, elapsed-seconds caption, error display, and post-generation "generated with AI — review before submitting" note all still behave as they do today.
• 2.6 German copy for any changed or added key is present and glossary-consistent; en and de are at parity for this namespace.

Prompt focus

• 3.1 Given the report-content generation prompt after the change, When it is read, Then it instructs the model to explain why each cost was incurred — its purpose or role in the construction project — and explicitly instructs it not to restate the vendor, invoice number, date, or amount, because those are already columns in the report table.
• 3.2 Given a set of invoices with budget lines and linked items, When AI enhancement runs with report language English, Then each returned usage description reads as a purpose statement (what the cost was for in the build) rather than a restatement of the row's own columns, and contains no vendor name, invoice number, or currency amount.
• 3.3 AC 3.2 holds identically when the report language is German: output is entirely in German (regardless of the interface language or the language of the source data), is grammatical, and uses natural German construction terminology consistent with the project glossary — no untranslated English fragments, no anglicised calques.
• 3.4 Given the cover-letter body prompt after the change, When AI enhancement runs, Then the generated body explains the purpose of the spending in the context of the construction project and its relevance to the report's purpose (overview / claim / proof of funds), rather than enumerating the invoices already listed in the table.
• 3.5 The existing safety and accuracy constraints are preserved verbatim in effect: untrusted-input / prompt-injection handling, "never invent or alter amounts or dates", "every invoice ID must appear in descriptions keyed by exact invoiceId", output language forced to the report language, and JSON-only output.
• 3.6 The numeric-accuracy guarantees established by feat(reports): AI-generated usage descriptions and cover letter for bank report wizard #1916 are untouched — amounts fed to the prompt remain in the correct unit and precision, and the existing prompts.test.ts regression guard against the ×100 unit defect continues to pass.

Length caps

• 4.1 Given the codebase after this change, When the maximum lengths for letterSubject, letterBody, and per-invoice description are looked up, Then each has exactly one definition, and both the prompt text and the response validator derive from that same definition — it is impossible for them to disagree.
• 4.2 The effective limits are: letterSubject 150 characters, letterBody 2000 characters, per-invoice description 200 characters.
• 4.3 Given an LLM response that exceeds any of those limits, When the response is validated, Then the field is capped to the limit (existing truncation behaviour) — the response is not rejected — and a test pins each boundary.

Notes

• Files: client/src/pages/ReportWizardPage/Step4Settings.tsx, client/src/pages/ReportWizardPage/ReportWizardPage.tsx, client/src/i18n/{en,de}/budget.json, server/src/services/budgetExtraction/prompts.ts, server/src/services/budgetExtraction/openAICompatibleProvider.ts (+ tests).
• Supersedes an item queued in refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups) #1917. refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups) #1917 carries a nit about buildReportContentUserPrompt L153, where the language ternary produces "German construction project" for English output and "Konstruktionsprojekt" for German — inverted and wrong in both branches. This issue rewrites that prompt wholesale and must fix that line as part of the rewrite. Remove the item from refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups) #1917 when this lands; leave the rest of refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups) #1917 open.
• Glossary: an approved German glossary entry for KI (AI) is outstanding — it was noted during the feat(reports): AI-generated usage descriptions and cover letter for bank report wizard #1916 review and folded into refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups) #1917. The existing de copy already uses "KI" ("Mit KI generieren", "KI-Unterstützung aktivieren"), so this issue must stay consistent with that; adding the formal glossary entry remains refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups) #1917's job.
• Interacts with the PDF-layout issue in this batch. Shorter, purpose-focused descriptions reduce Usage-column pressure, but the layout issue's ACs must hold independently of description length — neither issue may rely on the other for its fix.
• Scope guard: this issue does not change when AI runs (still user-initiated from step 5), does not add per-field AI regeneration, does not change the LLM provider/transport layer, and does not change the deterministic (non-AI) content that the wizard builds by default.

[steilerDev]

[ux-designer] Visual spec for the UI portion of this story (AC 1.1–1.3, Settings-step deletion; AC 2.1–2.6, Step 5 label/gating change). AC sections 3 and 4 are backend prompt/validator work and out of scope here.

This is a small, surgical change (a section removal + a relabel), so this spec is scoped to the design decisions that removal/relabel actually raise — not a full page spec.

Confirming the Frontend Spec's CSS-reuse decision: agreed, no objection. Reusing .aiGenerateRow / .aiGeneratingCaption / .aiGeneratedNote unchanged, and swapping only the gating condition (aiEnabled → llmEnabled) and the label, is correct — see §2 below for why the button's visual weight (btnSecondary, not btnPrimary) already reads as optional and doesn't need to change just because it's now unconditionally present rather than opt-in-revealed. And no rule ever targeted #enableAiAssistance — confirmed nothing is orphaned in CSS beyond the JSX/locale-key removal itself (AC 1.3).

1. Step 4 (Step4Settings.tsx) after removing the AI-assistance section

Layout uses a flex-column .settingsCard (gap: var(--spacing-4)) whose children are:

1. .settingsSection — Language (no top border; first child)
2. .settingsDivider — Document options (attach documents / cover letter) — owns its own border-top + padding-top
3. .settingsDivider — AI assistance — delete this entire block, including the {llmEnabled && (...)} wrapper (Step4Settings.tsx ~L109–128)

Because each section's separator is a top border that belongs to that section (not a trailing divider owned by the section above it), and spacing comes from the flex gap rather than margin-bottom hacks, deleting child 3 leaves no vestigial border, padding, or double-gap. Child 2 (document options) keeps its own top border unchanged — nothing about its styling depended on what used to follow it. No CSS changes needed in ReportWizardPage.module.css — .settingsDivider stays alive (still used by the document-options block), don't remove it.

Net result: .settingsCard simply ends after the document-options block. Verify visually that the card doesn't end with excess bottom padding — it shouldn't, since .settingsCard's own padding: var(--spacing-4) is on the outer container, not per-child.

Implementation hygiene note (not a visual defect, flagging so it doesn't get missed): Step4Settings.tsx's props (llmEnabled, aiEnabled, onAiEnabledChange) and ReportWizardPage.tsx's aiEnabled state (useState(false), ~L89) become dead once the gate moves to Step 5's llmEnabled check — remove them together rather than leaving inert wiring behind. llmEnabled itself is still needed (Step 5 still reads it), just no longer passed into Step4Settings. Per AC 1.3, sourceReports.settingsStep.enableAiAssistance / enableAiAssistanceHelper must be deleted from both en/budget.json and de/budget.json — no orphan keys.

2. Step 5 action — placement and prominence

Good news: no visual change needed. The existing treatment already reads correctly as an optional, user-initiated, non-primary action:

• .aiGenerateRow wraps the action in its own bordered card (background-color: var(--color-bg-secondary), border: 1px solid var(--color-border), radius-lg, padding-4) — visually separated from the ReportContentEditor content above/below it.
• The button itself uses sharedStyles.btnSecondary (outlined, --color-bg-tertiary background, --color-text-secondary text) — not btnPrimary. This is correct and must stay btnSecondary. Do not promote it to a primary CTA now that it's unconditionally visible for LLM-configured instances — its role (an optional enhancement, not a required wizard step) hasn't changed, only its gating condition has.
• The "overwrite your edits?" confirmation Modal (fires when overrides is non-empty) already carries the honesty-about-consequences requirement — that flow is unchanged and still fires on the same condition (Object.keys(overrides).length > 0), independent of how the button became visible.

So: keep .aiGenerateRow and btnSecondary exactly as-is. The "was this revealed by explicit opt-in vs. always-present" concern is a discoverability question, not a styling one, and is addressed by the label wording (§3) and the accessible description (§5), not by adding visual weight.

3. Label change (EN + DE)

• EN: sourceReports.editable.generateWithAi value changes from "Generate with AI" → "Enhance with AI" (AC 2.3). Optional cleanup: consider renaming the key itself to enhanceWithAi for long-term clarity, since it's only referenced in one place (ReportWizardPage.tsx L873) — not required, dev's call.

• DE recommendation: "Mit KI verbessern"

  Reasoning: existing copy in this namespace already establishes the pattern "Mit KI generieren" (generate) and "KI-Unterstützung aktivieren" (enable AI assistance) — both use "KI" as the noun, verb-first sentence structure. "Verbessern" (to improve/enhance) is the direct semantic match for "Enhance" — it signals improving something that already exists, which is exactly the product behavior (deterministic content is built first, AI then reworks it). I considered "Mit KI überarbeiten" (rework/revise) as an alternative — also acceptable, but "überarbeiten" leans toward "substantially rewrite," which slightly overstates it; "verbessern" is the tighter fit for AC 2.3's framing.

  Note: a formal KI glossary entry is outstanding (owned by refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups) #1917) — this recommendation is consistent with existing usage but isn't itself a glossary ruling. translator should implement "Mit KI verbessern" (or their own judgment call between the two options above) and flag if refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups) #1917 changes the guidance later.

• No other strings need to change — generating ("Generating… ({{seconds}}s)"), aiGeneratedNote, aiGenerationFailed, and the overwrite-confirm modal strings are all generic enough to still read correctly under the new label.

4. Regression check — in-flight / post-generation states

The whole action row is currently gated by a single condition swap: {aiEnabled && (...)} → {llmEnabled && (...)} (ReportWizardPage.tsx ~L860). Everything inside that block — the spinner (isGeneratingAi), the elapsed-seconds caption (aiElapsed, aria-live="polite" on .aiGeneratingCaption), the FormError for aiError, and the post-generation .aiGeneratedNote — is driven by its own state (isGeneratingAi / aiError / aiContent), not by aiEnabled. None of their entry conditions change: they still only appear once the user has clicked the button and a generation attempt has started/finished. No regression expected here; this is a clean swap of the outer gate only. No CSS changes needed to .aiGenerateRow, .aiGeneratingCaption, or .aiGeneratedNote.

5. Accessibility — button with no preceding opt-in

Today, the Step-4 checkbox's helper text (enableAiAssistanceHelper: "Let AI draft usage descriptions and a cover letter for you to review and edit.") gave every user — sighted and AT alike — a first introduction to the feature and its behavior before reaching Step 5. That framing disappears with the checkbox. Sighted users still get adequate context from the bordered .aiGenerateRow container and its position next to the editable content; screen-reader users navigating Step 5 linearly now hit the button with only its short label and no equivalent framing, and no way to know in advance that activating it can overwrite their edits.

Recommendation: add a static, visually-hidden description and wire it via aria-describedby — no visible layout change, so this doesn't conflict with §2's "don't add visual weight":

<button
  type="button"
  className={sharedStyles.btnSecondary}
  onClick={handleGenerateWithAiClick}
  disabled={isGeneratingAi}
  aria-describedby="ai-enhance-description"
>
  ...
  {t('sourceReports.editable.enhanceWithAi')}
</button>
<span id="ai-enhance-description" className={sharedStyles.srOnly}>
  {t('sourceReports.editable.enhanceWithAiDescription')}
</span>

Proposed EN copy for the new key sourceReports.editable.enhanceWithAiDescription:

"Replaces the report text and cover letter below with AI-generated content. You'll be asked to confirm before any edits you've made are overwritten."

Keep this description static (always present, not conditionally swapped based on overrides dirty-state) — a screen-reader user has no cheap way to sense their own dirty-state in advance, so describing the general behavior unconditionally is simpler and safer than trying to match the sighted-user's conditional-modal experience.

Everything else is already compliant and unchanged: it's a plain <button> in normal tab order, :focus-visible on .btnSecondary gets box-shadow: var(--shadow-focus), and .aiGeneratingCaption's aria-live="polite" stays as the sole live-region marker (don't also add role="status" — redundant).

Component Mapping

UI Element	Shared Component	Props/Variant	Notes
Enhance-with-AI button	plain <button> + sharedStyles.btnSecondary	—	Existing pattern, unchanged; do not promote to btnPrimary
In-flight spinner	Spinner	size="sm" color="muted"	Existing, unchanged
Generation error	FormError	message={aiError}	Existing, unchanged
Overwrite confirmation	Modal	footer with btnPrimary (confirm) + btnSecondary (cancel)	Existing, unchanged
New a11y description	sharedStyles.srOnly + aria-describedby	—	New: static, visually-hidden hint text (see §5)

No new shared components needed for this story.

[steilerDev]

[product-owner]

UAT scenarios — AC 3.2 / 3.3 (semantic output quality)

PR #1944 delivers every AC on this story that code can deliver. Two ACs cannot be closed by it:

• AC 3.2 — generated English usage descriptions read as purpose statements and contain no vendor name, invoice number, or currency amount.
• AC 3.3 — the same holds in German: fully German output, grammatical, natural construction terminology, no anglicised calques.

These assert live model output, not code. A mocked LLM returns whatever the fixture says, so a test claiming to verify them would be verifying the fixture author's prose, not the model's. QA was right not to write one. prompts.test.ts verifies the instruction (AC 3.1/3.4); it cannot verify the result.

These carry to UAT. Run with real LLM_* environment variables configured against a source with at least 5 invoices, mixed budget-line coverage, and at least one invoice with notes.

Scenario 3.2 — English output is a purpose statement

Given an instance with LLM_BASE_URL / LLM_API_KEY / LLM_MODEL configured
And a budget source with at least 5 invoices, at least one of which has notes and at least one of which has no budget lines
When I run the report wizard with report language English and click "Enhance with AI" on step 5
Then each Usage cell answers why the money was spent — what the purchase or service did for the build
And no Usage cell contains the vendor name, the invoice number, a date, or a currency amount
And no Usage cell is a verbatim or near-verbatim copy of the linked item name or budget-line description
And every invoice in the table has a non-empty Usage cell (none skipped)

Scenario 3.3 — German output is idiomatic German

Given the same instance and source
When I run the wizard with report language German and click "Mit KI verbessern"
Then every Usage cell and the entire cover letter are in German, with no untranslated English fragments
And the German reads as a native builder or bank correspondent would write it — no anglicised calques, no machine-literal renderings of English construction terms
And the same no-vendor / no-invoice-number / no-date / no-amount rule from 3.2 holds
And this is true regardless of the interface language — repeat once with the app in English and once in German; both must produce identical-language report output

Scenario 3.4 — Cover letter explains purpose, not contents

Given either language
When the cover letter body is read
Then it explains what the spending accomplished for the project and why, and ties that to the report's purpose (overview / claim / proof of funds)
And it does not re-list the individual invoices already shown in the table
And it references the source name, report type, and total amount, and those figures match the table's total exactly

Failure handling

If any scenario fails, this is a prompt-tuning defect against #1931, not a new story — reopen #1931 rather than filing a follow-up, since 3.2/3.3 are its own unmet criteria.

---

Story status: #1931 stays out of Done until these have been run by a human against a live model. PR #1944 merging does not close it.

[steilerDev]

[orchestrator] PR #1944 merged to beta (squash 128a5305).

This issue stays open deliberately. Per the product-owner's ruling on the PR, merge and Done are separate gates here: everything code can deliver is delivered and verified, but AC 3.2 and AC 3.3 describe live-model output quality (generated text reading as a purpose statement; natural, calque-free German) and cannot be asserted against a mocked LLM. No test claims to verify them.

Remaining to close: run the UAT scenarios posted on this issue against an instance with LLM_* configured, reviewing generated output in both English and German. If UAT fails, reopen work against this issue rather than filing a follow-up — these are its own unmet criteria.

Moved to Todo on the board pending that verification.