trace-first-starter

HL — TFW-23: Templates English Standardization

Date: 2026-04-04 Author: Coordinator Status: 📝 HL_DRAFT — Awaiting review

---

1. Vision

Templates are the DNA of TFW — every artifact starts from a template. Currently 5 of 9 templates have mixed Russian/English content (RU headings, EN body, RU annotations). This creates inconsistency, wastes tokens, and confuses AI agents that work better with English prompts.

Goal: All templates → pure English. AI agents fill them in the user’s language at runtime.

“Templates are code. Code is English. Content is user’s language.”

2. Current State (As-Is)

Template	Language	RU Elements
HL.md	Mixed	Дата, Автор, Статус, Видение, Текущее состояние, Целевое состояние, Визуализация результата, Фазы, Принципы, Зависимости, Риски, Обоснование RESEARCH, Слепые зоны, Гипотезы, Фильтр, Риски незнания, Предлагаемый фокус, При провале
TS.md	Mixed	Дата, Автор, Статус, Цель, Затрагиваемые файлы, Файл, Действие, Описание, Бюджет, Риски фазы
RF.md	Mixed	Дата, Автор, Статус, Что сделано, Новые файлы, Файл, Описание, Изменённые файлы, Изменения, Ключевые решения, Верификация
ONB.md	Mixed	Дата, Автор, Статус, RU annotations in parentheses
REVIEW.md	Mixed	Дата, Автор
RES.md	✅ English	—
KNOWLEDGE.md	✅ English	—
RELEASE.md	✅ English	—
TOPIC_FILE.md	✅ English	—

Token waste estimate: ~150-200 tokens of Cyrillic per template × 5 templates = ~800-1000 wasted tokens per full task cycle (HL+TS+ONB+RF+REVIEW).

3. Target State (To-Be)

All 9 templates in .tfw/templates/ use English for:

• Section headings
• Field labels (Date, Author, Status)
• Table headers
• Instructional text / annotations
• Placeholders

3.1 Result Visualization

BEFORE (HL.md):                          AFTER (HL.md):
┌────────────────────────┐               ┌────────────────────────┐
│ > **Дата**: YYYY-MM-DD │               │ > **Date**: YYYY-MM-DD │
│ > **Автор**: {author}  │               │ > **Author**: {author} │
│ > **Статус**: 📝 ...   │               │ > **Status**: 📝 ...   │
│                        │               │                        │
│ ## 1. Видение          │               │ ## 1. Vision           │
│ ## 2. Текущее состояние│     ───►      │ ## 2. Current State    │
│ ## 3. Целевое состояние│               │ ## 3. Target State     │
│ ## 7. Принципы         │               │ ## 7. Principles       │
│ ## 8. Зависимости      │               │ ## 8. Dependencies     │
│ ## 9. Риски            │               │ ## 9. Risks            │
│ ## 10. Обоснование ... │               │ ## 10. RESEARCH Case   │
└────────────────────────┘               └────────────────────────┘

Status labels:
  "📝 HL_DRAFT — Ожидает ревью"  →  "📝 HL_DRAFT — Awaiting review"
  "🟡 TS_DRAFT — Ожидает апрува" →  "🟡 TS_DRAFT — Awaiting approval"
  "🟠 ONB — Ожидает ответов"     →  "🟠 ONB — Awaiting answers"
  "🟢 RF — Выполнено"            →  "🟢 RF — Complete"

4. Phases

Phase A: Template Standardization ✅

• Translate all 5 mixed-language templates to English (headings, field labels, table headers, instructional annotations)
• Use consistency table from RES E1 for all translations
• Update KNOWLEDGE.md §3 legacy entry (line 133) to match new EN headings
• Preserve exact structure, section numbers, placeholders
• No content changes — only language

Phase B: Content Language Config 🔴

• Add tfw.content_language: en to PROJECT_CONFIG.yaml
• Add a convention rule to conventions.md: agents fill content in the language from config
• Update tfw-init workflow: ask user for preferred content language during init
• Register in Config Sync Registry (conventions.md §12)

5. Definition of Done (DoD)

• ✅ 1. All 9 templates in .tfw/templates/ are 100% English
• ✅ 2. Zero Cyrillic characters in any template file (headings, labels, tables, instructional annotations)
• ✅ 3. Section structure and numbering unchanged
• ✅ 4. Placeholder syntax ({author}, {PREFIX}, etc.) unchanged
• ✅ 5. No semantic drift — every EN heading maps 1:1 to the original RU heading (per RES consistency table)
• ✅ 6. KNOWLEDGE.md §3 legacy entry updated to match new heading names
• ✅ 7. tfw.content_language config key exists in PROJECT_CONFIG.yaml with default en
• ✅ 8. Convention rule documents how agents use content_language
• ✅ 9. tfw-init asks user for preferred content language

6. Definition of Failure (DoF)

• ❌ 1. Template structure changes (sections added/removed/renumbered)
• ❌ 2. Placeholder format changes
• ❌ 3. Inconsistent translation — same RU term translated differently across templates

On failure: revert, re-translate with consistency table.

7. Principles

1. Templates = code — code is English, always
2. Content follows user — AI fills templates in user’s language, template structure stays English
3. Zero semantic drift — EN headings must carry the same meaning as RU originals
4. Consistency across templates — same field name everywhere (Date, Author, Status, File, Description, Action)
5. Naming > Explanation (D28) — heading names chosen to trigger correct agent behavior, not just describe content

8. Dependencies

Dependency	Status
None	✅

9. Risks

Risk	Probability	Impact	Mitigation
Inconsistent translation across templates	Low	Medium	Use consistency table (§7 P4)
Existing filled artifacts reference old headings	N/A	N/A	Filled artifacts are not affected — templates change, not past outputs

10. RESEARCH Case

RESEARCH completed. See RES for full analysis.

Hypotheses

#	Hypothesis	Status	Evidence
H1	RES.md is already fully English	✅ confirmed	File inspection
H2	KNOWLEDGE.md, RELEASE.md, TOPIC_FILE.md are already English	✅ confirmed	File inspection
H3	No workflows reference template headings by RU name	✅ confirmed	Grep: workflows use §numbers, not heading text (RES G4)

Key RES Decisions

• D1: English-only templates, content in user’s language (industry standard)
• D2: 32-term consistency table built with D28 (Naming > Explanation)
• D3: content_language config deferred to future task
• D4: RU instructional annotations also need translation
• D5: KNOWLEDGE.md §3 legacy entry needs update

---

*HL — TFW-23: Templates English Standardization

2026-04-04*

This site is open source. Improve this page.