Date: 2026-04-04 Author: Coordinator Status: 🔬 RES — In progress Parent HL: HL-TFW-23 Mode: Pipeline / Focused
5 of 9 TFW templates have mixed Russian/English content. Goal: standardize all to English. This research validates the approach — translation consistency, community practices for multilingual template frameworks, and whether any downstream artifacts/workflows would break.
Статус line use the same phrasing as PROJECT_CONFIG status descriptions, or keep the current human-friendly labels?| # | Hypothesis | HL Status | RES Status | Evidence |
|---|---|---|---|---|
| H1 | RES.md is already fully English | confirmed | ✅ confirmed | Verified by reading file |
| H2 | KNOWLEDGE.md, RELEASE.md, TOPIC_FILE.md are already English | confirmed | ✅ confirmed | Verified by reading files |
| H3 | No workflows reference template headings by RU name | open | 🟡 testing |
→ User direction: ___
| # | Decision | Rationale |
|—|———-|———–|
| D1 | English-only templates, content filled in user’s language | Industry standard (G1). Templates = code → code is English |
| D2 | Use consistency table from E1 for all translations | D28: “right terminology creates right associations”. 32 terms mapped |
| D3 | content_language config deferred to future task | Challenge C1: mixing features violates scope. TFW-20 or new task |
| D4 | Translate RU instructional annotations too, not just headings | Challenge C3: instructions are part of template structure |
| D5 | Update KNOWLEDGE.md §3 legacy entry to match new EN headings | Challenge C4: avoid confusion when agents read legacy table |
| D6 | H3 confirmed: workflows reference §numbers, not heading text | Grep verification (G4). Renaming is safe |
| D7 | §3.1 instructional block: Variant A (principle + domain examples). §10 filter: literal translation. Both rewritten to be domain-agnostic — TFW is not code-only | User feedback: HL instructions too tech-focused, TFW serves education, business, research too |
| # | Question | Status | Answer |
|—|———-|——–|——–|
| 1 | Best EN terms for ambiguous RU headings? | ✅ resolved | Consistency table in E1 — D28 applied to each term |
| 2 | Status line phrasing source? | ✅ resolved | Short labels: “Awaiting review”, “Awaiting approval”, “Complete” |
| 3 | i18n / fork considerations? | ✅ resolved | Document principle in HL. content_language config = future task |
External research confirms: English structure + localized content is the industry standard pattern. Key finding: “Language-Agnostic Core — keep the core system logic consistent across all languages. Only localize the tone, style, and cultural adaptation parts.” This is exactly what TFW needs — templates = core logic (English), filled content = user language.
| Option | Description | Complexity | Fit |
|---|---|---|---|
| A. English-only templates | Templates in EN, agents fill in user’s language | Low | ✅ Best — simple, no infra |
| B. Locale directories | templates/en/HL.md, templates/ru/HL.md |
High | ❌ File explosion, sync nightmare |
| C. YAML key-value i18n | {t.vision} placeholders, resolved from locale file |
Medium | ❌ Over-engineered for markdown |
| D. Config-driven content language | tfw.content_language: en in config, agent uses it for filling |
Low | ✅ Good — configurable without file duplication |
Conclusion: Option A + D hybrid is best. Templates stay English (Option A). Config has tfw.content_language (Option D) that tells the agent which language to use when filling the template. Default = en. During tfw-init, ask user preferred language.
Per D28 (“Naming > Explanation”) and P5 (“right terminology creates right associations”):
Grep confirmed: workflows reference sections by § number (§3.1, §10), never by heading text. Zero RU heading references in any workflow file. Renaming headings is safe.
| Found | Remaining | |——-|———–| | i18n best practice = EN structure, localized content | — | | 4 architecture options evaluated, A+D hybrid selected | — | | D28 naming principle applicable to heading translation | translation table (→ Extract) | | H3 confirmed: no workflow refs to RU headings | — |
Sufficiency Verdict:
Agent assessment: Gather is sufficient. Architecture decision made (A+D hybrid). H3 confirmed. Depth check: 3 external web searches used (i18n practices, naming conventions, locale config patterns). Recommendation: close stage, move to Extract for naming table Stage complete: YES → User decision: ___
Method: For each RU heading, identify the behavior it should trigger in the agent. Then find the shortest English term that the AI already associates with that behavior (D28: “right terminology creates right associations”).
| RU Original | EN Translation | D28 Rationale |
|---|---|---|
Дата |
Date |
Universal |
Автор |
Author |
Universal |
Статус |
Status |
Universal |
Ожидает ревью |
Awaiting review |
Short, clear intent |
Ожидает апрува |
Awaiting approval |
Standard process term |
Ожидает ответов |
Awaiting answers |
Direct, no ambiguity |
Выполнено |
Complete |
Shortest possible |
| § | RU Original | Candidate A | Candidate B | Winner | D28 Rationale |
|---|---|---|---|---|---|
| 1 | Видение |
Vision |
Goal |
Vision | Standard strategic planning term; agents associate it with “why + business value” |
| 2 | Текущее состояние (As-Is) |
Current State (As-Is) |
As-Is |
Current State (As-Is) | Already has EN annotation; keep both for scan-ability |
| 3 | Целевое состояние (To-Be) |
Target State (To-Be) |
To-Be |
Target State (To-Be) | Mirror of §2 |
| 3.1 | Визуализация результата |
Result Visualization |
Outcome Preview |
Result Visualization | Agents associate “visualization” with diagrams/ascii — exactly what we want |
| 4 | Фазы |
Phases |
Roadmap |
Phases | Direct translation; TFW uses “Phase” heavily |
| 5 | Definition of Done (DoD) |
— | — | Keep | Already EN |
| 6 | Definition of Failure (DoF) |
— | — | Keep | Already EN |
| 7 | Принципы |
Principles |
Design Philosophy |
Principles | Short, standard. Section body already says “Design philosophy” |
| 8 | Зависимости |
Dependencies |
Prerequisites |
Dependencies | Standard engineering term |
| 8 tbl | Зависимость \| Статус |
Dependency \| Status |
— | Dependency | Status | Direct |
| 9 | Риски |
Risks |
— | Risks | Universal |
| 9 tbl | Риск \| Вероятность \| Влияние |
Risk \| Probability \| Impact |
Risk \| Likelihood \| Severity |
Risk | Probability | Impact | Standard risk matrix terms |
| 9 tbl | Низкая/Средняя/Высокая |
Low/Medium/High |
— | Low/Medium/High | Universal |
| 10 | Обоснование RESEARCH |
RESEARCH Case |
RESEARCH Justification |
RESEARCH Case | Shorter. “Case” = argument. Agents associate “case” with “make this argument” |
| 10.1 | Слепые зоны |
Blind Spots |
Unknown Unknowns |
Blind Spots | Already used in workflows in EN. AI associations: strong |
| 10.2 | Гипотезы |
Hypotheses |
— | Hypotheses | Standard scientific term |
| 10.2 tbl | Гипотеза \| Статус |
Hypothesis \| Status |
— | Hypothesis | Status | Direct |
| 10.3 | Фильтр |
Filter |
— | Filter | Direct. But the content is more important — translate the instruction |
| 10.4 | Риски незнания |
Risks of Not Researching |
Ignorance Risks |
Risks of Not Researching | Explicit, no ambiguity |
| 10.5 | Предлагаемый фокус RESEARCH |
Proposed RESEARCH Focus |
— | Proposed RESEARCH Focus | Direct, clear |
| footer | При провале |
On failure |
— | On failure | Short |
| § | RU Original | Winner | D28 Rationale |
|---|---|---|---|
| 1 | Цель |
Objective | Stronger action signal than “Goal”; agents associate “objective” with deliverable |
| 3 | Затрагиваемые файлы |
Affected Files | Standard term in PR/diff tooling |
| 3 tbl | Файл \| Действие \| Описание |
File | Action | Description | Direct |
| 3 note | Бюджет |
Budget | Direct; already used in EN context |
| 6 | Риски фазы |
Phase Risks | Mirror HL §9 |
| § | RU Original | Winner | D28 Rationale |
|---|---|---|---|
| 1 | Что сделано |
What Was Done | Direct, action-past |
| 1.1 | Новые файлы |
New Files | Direct |
| 1.2 | Изменённые файлы |
Modified Files | Standard term (git) |
| 1 tbl | Файл \| Описание, Файл \| Изменения |
File | Description, File | Changes | Direct |
| 2 | Ключевые решения |
Key Decisions | Direct |
| 4 | Верификация |
Verification | Direct |
| § | RU Original | Winner | D28 Rationale |
|---|---|---|---|
| 1 | Understanding (как понял задачу) |
Understanding | Drop RU annotation |
| 2 | Entry Points (откуда начинать) |
Entry Points | Drop RU annotation |
Only Дата, Автор — covered in common fields.
content_language config patternProposed addition to PROJECT_CONFIG.yaml:
tfw:
content_language: en # Language for filled artifacts (en, ru, etc.)
Agent instruction (goes in conventions.md or AGENTS.md):
“When filling templates, use the language specified in
tfw.content_language. Template structure (headings, labels, field names) stays English always.”
During tfw-init, agent asks: “What language should I use when filling artifacts? Default: English.”
KNOWLEDGE.md line 133 has:
§3.1 Визуализация результата (ascii mandatory), §10 Обоснование RESEARCH (hypotheses + blind spots)
This is a historical record (Source column = TFW-22). Will need updating to match new EN headings.
| Found | Remaining | |——-|———–| | Full translation table for 5 templates (32 term pairs) | — | | content_language config pattern designed | — | | KNOWLEDGE.md §3 needs historical record update | HL scope update |
Sufficiency Verdict:
Agent assessment: Extract is sufficient. Complete consistency table built. No gaps remaining. Depth check: Project knowledge (D28, P5) + convention analysis + grep verification of downstream refs. Recommendation: close stage, move to Challenge Stage complete: YES → User decision: ___
content_language overengineering?Argument FOR: User explicitly asked for it. Minimal implementation — one YAML key + one sentence in conventions.md. Enables non-English users without template duplication.
Argument AGAINST: If we add it now, we need to:
PROJECT_CONFIG.yamltfw-init workflow (ask user)/tfw-config)This is not template standardization — it’s a new feature. Mixing it into TFW-23 violates scope.
Verdict: Split content_language into a separate concern. TFW-23 = English templates only. The content_language feature can be part of TFW-20 (user preferences) or a new task. Today we document the principle: “templates = English, content = user’s language” in the HL, but don’t implement the config mechanism.
Testing a few critical names against alternatives:
| Term | Why it works (D28) | Risk |
|---|---|---|
| Vision (§1) | AI models are trained on business docs — “Vision” triggers strategic framing, not just description | Low — universally understood |
| Objective (TS §1) vs “Goal” | “Objective” is more specific: “measurable deliverable”. “Goal” is vaguer. In military/project contexts, “objective” = concrete target | Low |
| RESEARCH Case (§10) vs “RESEARCH Justification” | “Case” = shorter, implies “make the argument”. “Justification” = reactive, implies “defend a decision already made”. “Case” is proactive | Low |
| Result Visualization (§3.1) vs “Outcome Preview” | “Visualization” literally tells the agent to produce a visual (diagram, ascii). “Preview” is passive — could mean just text description | Winner: Result Visualization confirmed |
No alternative names are clearly better. The consistency table from Extract holds.
Lines 23-28 in HL.md are RU instructional text:
> Покажи результат как будто он уже достигнут. Используй:
> - **ASCII-схемы** (обязательно): ...
> - **Mermaid** (для complex flows): ...
> - **Before→After таблицы** для сравнения state
> Цель: исполнитель и юзер должны увидеть «финальную картинку» до начала работы.
And line 88:
> **Фильтр:** Каждая гипотеза: «Если окажется ложной — изменится ли наш подход?» Если нет — удалить.
These are instructional annotations, not headings. They also need translation. I missed these in the initial HL scope. Must be included.
Line 133 in KNOWLEDGE.md has §3.1 Визуализация результата. This is a Legacy & Deprecation record. The convention (P2: “Index, don’t duplicate”) says link to sources. The §3.1 heading name is descriptive context in the legacy table. It should be updated to reflect the new name to avoid confusion when agents read it.
| Found | Remaining |
|——-|———–|
| content_language = separate concern, not TFW-23 scope | Document principle in HL only |
| Naming table confirmed — no alternatives are clearly better | — |
| RU instructional text inside templates needs translation too | Add to HL scope |
| KNOWLEDGE.md historical entry needs update | Add to HL scope |
Sufficiency Verdict:
Agent assessment: Challenge revealed 2 scope additions (instructional text, KNOWLEDGE.md) and 1 scope reduction (content_language → future task). Net change is minor. Depth check: Internal analysis of assumptions, external D28 cross-reference. Recommendation: close stage, proceed to Final Checkpoint Stage complete: YES → User decision: ___
| Stage | Status | Key Findings |
|---|---|---|
| Gather | ✅ Done | EN structure + localized content = industry standard. A+D hybrid architecture. H3 confirmed (no RU heading refs in workflows) |
| Extract | ✅ Done | 32-term consistency table built (D28 applied). content_language config pattern designed. KNOWLEDGE.md legacy entry found |
| Challenge | ✅ Done | content_language = separate task (scope reduction). RU instructional text also needs translation (scope addition). KNOWLEDGE.md entry update needed |
Question: Sufficient for HL finalization? Can we confidently define phases, approach, and dependencies? Self-check:
Verdict: Sufficient for HL finalization
| # | What to update | Source |
|—|—————|——–|
| 1 | Add RU instructional text (HL.md lines 23-28, 88) to scope — not just headings | C3 |
| 2 | Add KNOWLEDGE.md §3 legacy entry update to scope | C4 |
| 3 | Remove content_language config from TFW-23 scope → note as future (TFW-20 or new task) | C1 |
| 4 | Add consistency table reference to HL (or keep in RES as source of truth) | E1 |
| 5 | Document principle: “templates = English, content = user’s language” in HL §7 | C1 |
Update HL → confirm → TS → User decision: ___
| # | Category | Candidate | Source | Confidence |
|---|---|---|---|---|
| 1 | convention | Templates = English always; filled content = user’s language. Template structure is code, code is English | User direction + external i18n best practice | High |
| 2 | convention | content_language as a config key is the right pattern for i18n in TFW — avoids template duplication, avoids locale directories, minimal infra. Implementation deferred |
RES G2 analysis | Medium |
| 3 | process | D28 (Naming > Explanation) applies not just to workflow terms but also to template section headings — heading names should trigger correct agent behavior, not just describe content | RES E1 + C2 analysis | High |
Research confirmed that English-only templates with user-language content is the industry standard for AI prompt frameworks. A 32-term consistency table was built applying D28 (Naming > Explanation), choosing terms that trigger correct agent behavior. Challenge stage refined scope: content_language config is a separate feature (deferred), while RU instructional annotations and KNOWLEDGE.md legacy entries were added to scope. All hypotheses confirmed. No unknowns remain.
| *RES — TFW-23: Templates English Standardization | 2026-04-04* |