MicroFish/.kiro/specs/i18n-report-agent-prompts/research.md

# Research & Design Decisions — i18n-report-agent-prompts

## Summary

- **Feature**: `i18n-report-agent-prompts`
- **Discovery Scope**: Extension (single-file in-place translation, established sibling-spec precedent)
- **Key Findings**:
  - The full LLM-message-stream Chinese surface in `report_agent.py` is ~2680 chars across 7 top-level prompt constants, 4 tool-description blocks, ~10 inline f-strings/templates inside `_generate_section_react` and `chat`, the `_execute_tool` error returns, and the `plan_outline` defaults — ~4× the ticket's "~609 char" estimate.
  - The four sibling i18n PRs (#2/#3/#4 commits `0806832`, `9d1d29b`, `6c2a412`) established in-place translation in a single file as the pattern; reviewer expectations and PR shape are already locked in.
  - Two cross-cutting literals must be preserved byte-for-byte: the trigger string `Final Answer:` (matched by `_generate_section_react` line 1327) and the XML tag `<tool_call>` (matched by `_parse_tool_calls` regex). All translated prompts continue to reference these literals exactly.

## Research Log

### Topic: How does locale switching work today and what guarantees does it give?

- **Context**: R9 of requirements depends on `get_language_instruction()` continuing to bias the model into the requested locale even after the base prompt is English.
- **Sources Consulted**: `backend/app/utils/locale.py`; `locales/languages.json`; `locales/en.json`; `locales/zh.json`; sibling-spec gap-analysis for issue #4 (`.kiro/specs/i18n-simulation-config-generator-prompts/gap-analysis.md`).
- **Findings**:
  - `get_language_instruction()` resolves locale from the Flask `Accept-Language` header (or thread-local in background threads) and returns a per-locale postfix string (`Please respond in English.` for `en`, `请使用中文回答。` for `zh`, etc.).
  - `languages.json` registers `zh`, `en`, `es`, `fr`, `pt`, `ru`, `de`. All non-`zh` postfixes are already in English.
  - Sibling spec #4 verified that an English-base prompt + `请使用中文回答。` postfix produces Chinese output of equivalent quality to the prior Chinese-base prompt for the simulation-config flow. The same mechanism applies here — there is no report-agent-specific locale path.
- **Implications**: The translation does not need to touch `locale.py` or `/locales/*`. Preserving the three `get_language_instruction()` call sites verbatim is sufficient for R9.

### Topic: Which literal trigger strings does the ReACT loop parser match?

- **Context**: R2 acceptance criterion 6 and R4 acceptance criterion 4 require that translated prompts continue to use literal trigger strings the parser depends on.
- **Sources Consulted**: `backend/app/services/report_agent.py` lines 1067–1126 (`_parse_tool_calls`, `_is_valid_tool_call`); 1327 (`has_final_answer = "Final Answer:" in response`); 1838, 1874 (chat regex `<tool_call>.*?</tool_call>`).
- **Findings**:
  - `Final Answer:` is matched as a Python literal substring (case-sensitive). Translation must keep this English token byte-for-byte.
  - `<tool_call>` and `</tool_call>` are matched by `re.search(r'<tool_call>(.*?)</tool_call>', response, re.DOTALL)` (line 1080-ish, in `_parse_tool_calls`). Translation must keep these XML tags byte-for-byte.
  - `_is_valid_tool_call` accepts both `{"name": ..., "parameters": ...}` and `{"tool": ..., "params": ...}` shapes, normalizing to `name`/`parameters`. Translation does not affect this.
- **Implications**: Translated prompts continue to instruct the model using the same literal example block; only the surrounding natural-language Chinese is rewritten in English.

### Topic: Are there Chinese illustrations embedded inside the section system prompt that must also translate?

- **Context**: `SECTION_SYSTEM_PROMPT_TEMPLATE` (615–767) contains code-fenced "正确示例" / "错误示例" blocks with Chinese sample text. These are formatting-contract illustrations, not data.
- **Sources Consulted**: `report_agent.py` lines 678–703.
- **Findings**:
  - The "正确示例" block (lines 678–694) shows a sample paragraph using `**bold**`, `>` block quotes, and lists — Chinese text demonstrating the no-headings rule.
  - The "错误示例" block (lines 696–703) shows wrong patterns (`## 执行摘要`, `### 一、首发阶段`, etc.) with Chinese text labeled as errors.
  - These are illustrative only — the model uses them to internalize the format contract. Translating them to semantically equivalent English (sample paragraph about, e.g., a generic event using English bold/quotation/list patterns; wrong patterns showing English headings labeled as errors) preserves the contract.
- **Implications**: The section system prompt translation must rewrite both example blocks in English while keeping the structural rule (use `**bold**`, `>`, lists; do not use `#`, `##`, `###`, `####`).

### Topic: Are there Chinese strings that flow through `t(...)` keys (vs raw literals)?

- **Context**: R12 carves out `logger.*` calls already routed via `t('...')` (issue #6). Need to confirm we are not double-counting strings.
- **Sources Consulted**: `report_agent.py`; `locales/en.json`; `locales/zh.json`.
- **Findings**:
  - 47 of 48 `logger.*` calls in `report_agent.py` already use `t('report.*')` or `t('progress.*')` keys — those are out of scope.
  - One raw Chinese f-string remains: `logger.debug(f"LLM响应: {response[:200]}...")` at line 1322. This is a logger call (not a prompt string sent to the LLM). It belongs to issue #6, and leaving it untouched is consistent with the ticket boundary "logger calls in this file are covered by #6".
  - `progress_callback(...)` calls receive `t('progress.*')` localized strings — those flow to the frontend, not to the LLM, and are out of scope.
- **Implications**: After translation, a single Chinese f-string in `report_agent.py` remains (line 1322 logger.debug). This is acceptable per the ticket's R12 carve-out.

### Topic: How do consumers downstream of `Report.to_dict()` and `chat()` deal with localized output?

- **Context**: R10 / R11 — preserving the public surface so the report API and the chat endpoint continue to work unchanged.
- **Sources Consulted**: `backend/app/api/report.py`; `frontend/src/api/report.js`; `frontend/src/components/Step5*.vue`.
- **Findings**:
  - The report API blueprint hands `Report.to_dict()` and the chat response payload to the frontend without locale-specific post-processing. The frontend renders `report.title`, `report.summary`, and `report.sections[*].title/content` as plain text/Markdown.
  - There are no string-equality checks against Chinese substrings on the consumer side. Translating the fallback outline to English is safe.
- **Implications**: R8 (translate fallback outline) and R10 (preserve surface) are independently verifiable — no consumer-side adaptation required.

## Architecture Pattern Evaluation

| Option | Description | Strengths | Risks / Limitations | Notes |
|--------|-------------|-----------|---------------------|-------|
| In-place translation (A) | Edit Chinese string-literals in `report_agent.py` directly | Matches precedent of #2/#3/#4; minimal blast radius; no new files | Translations are baked in; non-`zh`/`en` locales still rely on postfix bias | **Selected** — same pattern, same scope |
| Externalize to `/locales/` (B) | Move all prompt content to `locales/en.json` / `locales/zh.json` and resolve via `t(...)` | Genuinely locale-agnostic; could later support es/fr/pt/ru/de natively | Touches `/locales/` (forbidden by R12); diverges from sibling pattern; brace-escape risk in JSON | Rejected — breaks R12 |
| Hybrid externalization (C) | Externalize top-level constants; keep inline f-strings in code | Captures largest blocks in localizable form | Two-tier inconsistency; same R12 violation; no precedent | Rejected — same R12 issue |

## Design Decisions

### Decision: In-place translation in a single file

- **Context**: Translate ~2680 Chinese characters across all LLM-facing string-literals in `backend/app/services/report_agent.py`.
- **Alternatives Considered**:
  1. Externalize all prompts to `/locales/*.json` and resolve via `t(...)`.
  2. Hybrid: externalize the seven top-level constants only.
- **Selected Approach**: In-place translation in `report_agent.py`. Edit each string-literal directly. No new files, no new abstractions.
- **Rationale**: Four sibling i18n PRs (issues #2/#3/#4) used the same pattern. Precedent is locked in; reviewer expectations are clear; PR shape is predictable. R12 explicitly forbids `/locales/` edits.
- **Trade-offs**: ✅ smallest blast radius, ✅ matches reviewer pattern. ❌ es/fr/pt/ru/de still rely on postfix bias (already true today; not a regression).
- **Follow-up**: Run `python -m py_compile backend/app/services/report_agent.py` post-edit; run a regex sweep verifying zero Chinese chars in any LLM-facing string-literal (the line-1322 `logger.debug` is exempt — issue #6).

### Decision: Translate embedded Chinese examples in `SECTION_SYSTEM_PROMPT_TEMPLATE`

- **Context**: The section system prompt contains "正确示例" / "错误示例" code blocks (lines 678–703) with Chinese sample text. R2 AC1 demands zero Chinese in any string-literal content.
- **Alternatives Considered**:
  1. Drop the example blocks entirely (shorter prompt, less guidance for the model).
  2. Translate to semantically equivalent English illustrations.
  3. Keep Chinese examples and append an English translation in parallel.
- **Selected Approach**: Translate to English. The "Correct Example" shows a sample paragraph about a generic scenario using `**bold**`, `>` block quotes, lists, and no headings. The "Wrong Example" shows wrong English headings (`## Executive Summary`, `### 1. First Stage`, etc.) labeled as errors.
- **Rationale**: The examples drive the model's understanding of the no-headings format contract. Removing them risks regressing format compliance. Parallel Chinese-then-English bloats the prompt and re-introduces Chinese tokens. English-only is the cleanest match for an English-base prompt.
- **Trade-offs**: ✅ preserves format contract, ✅ single-language base prompt. ❌ slight prompt-length growth (negligible vs total context).
- **Follow-up**: Spot-check a single end-to-end report run under `Accept-Language: en` to confirm the model still avoids Markdown headings in section bodies.

### Decision: Switch `"、".join(unused_tools)` to `", ".join(...)`

- **Context**: Line 1454 currently does `unused_tools_str = "、".join(unused_tools)`, where `、` is the Chinese enumeration comma. This list flows into `REACT_OBSERVATION_TEMPLATE` and into the inline f-strings at lines 1380 and 1476.
- **Alternatives Considered**:
  1. Keep `"、"` (Chinese punctuation).
  2. Switch to `", "` (English-friendly).
  3. Keep `"、"` for `zh`, `", "` for `en` (locale-conditional).
- **Selected Approach**: Switch to `", "` unconditionally.
- **Rationale**: The join result is interpolated into the now-English ReACT templates. Keeping the Chinese enumeration comma in English context reads as a typo. Locale-conditional behavior here would re-introduce Chinese tokens into the message stream when `zh` is the locale (acceptable but inconsistent with the rest of the message). The model already follows `get_language_instruction()` for output, so the join punctuation does not need to localize.
- **Trade-offs**: ✅ natural English rendering, ✅ single code path. ❌ a `zh`-locale developer reading the code might find the all-English separator slightly off — minor stylistic concern only.
- **Follow-up**: None — this is a one-line change.

### Decision: Standard English phrasing for recurring framing terms

- **Context**: The Chinese prompts use recurring framing tokens that need consistent English equivalents. Inconsistent translations (e.g. "scenario" in one place, "brief" in another) hurt the prompt's coherence.
- **Selected Approach**: Pick once, use everywhere:
  - 上帝视角 → "all-seeing observer's perspective" / "god's-eye view" (use the latter; shorter, more idiomatic)
  - 未来预演 → "forecast simulation" / "simulated future"
  - 模拟需求 → "simulation requirement" (matches the variable name `simulation_requirement`)
  - 上下文 → "context"
  - 章节 → "section"
  - 报告 → "report"
  - 大纲 → "outline"
  - 正确示例 → "Correct Example"
  - 错误示例 → "Wrong Example"
  - 重要 → "IMPORTANT"
  - 注意 → "Note"
  - 工具 → "tool"
  - 检索 → "retrieval"
  - 章节标题 → "section title"
  - 模拟世界 → "simulated world"
  - 引用 → "quote" / "quotation"
- **Rationale**: Internal consistency lets the model build a coherent mental model of the task vocabulary. Aligning with variable names (e.g. `simulation_requirement`) reduces translation surface ambiguity.
- **Trade-offs**: ✅ consistent vocabulary across translated regions. ❌ none.
- **Follow-up**: None — list serves as a glossary for the implementer.

## Risks & Mitigations

- **Risk**: Translated section system prompt drops a structural cue the Chinese version was carrying, regressing `zh` quality. **Mitigation**: Preserve all interpolations, the JSON schema, the no-headings rule, the language-consistency rule, the format-contract examples (now in English), and the `get_language_instruction()` postfix. Spot-check a `zh` run if feasible.
- **Risk**: A Chinese substring slips through (e.g. inside a hard-to-spot ReACT message). **Mitigation**: Run a regex sweep `re.findall(r'[一-鿿]', source)` after the edit; the only allowed remaining match is the line-1322 `logger.debug` Chinese f-string.
- **Risk**: Reformatting `SECTION_SYSTEM_PROMPT_TEMPLATE` damages the literal `<tool_call>` example or shifts the `Final Answer:` token. **Mitigation**: Use targeted `Edit` replacements that preserve the surrounding code block; verify after edit that `"Final Answer:" in response` still triggers the parser branch.
- **Risk**: The `"、".join(...)` separator change leaks into a Chinese-language render path. **Mitigation**: The separator only flows into ReACT templates that are already monolingually English in this PR; no `zh`-specific render path consumes it.

## References

- Issue #5 ticket body: `.ticket/5.md`.
- Sibling spec: `.kiro/specs/i18n-simulation-config-generator-prompts/{requirements,design,gap-analysis}.md`.
- Sibling commits: `0806832` (#2 ontology), `9d1d29b` (#3 oasis profile), `6c2a412` (#4 simulation config).
- Locale module: `backend/app/utils/locale.py`.
- Locale registry: `locales/languages.json`, `locales/en.json`, `locales/zh.json`.