HL — TFW-18: Knowledge Consolidation¶
Дата: 2026-04-03 Автор: Coordinator (AI) Статус: 📝 HL_DRAFT — Updated after RESEARCH (RES-TFW-18)
1. Видение¶
Знания проекта сейчас теряются между чатами. Агенты выполняют задачи, в ходе работы узнают о проекте новые факты — архитектурные ограничения, внешние зависимости, бизнес-контекст, поведение инфраструктуры — но нигде их не фиксируют. RF записывает Observations (tech debt), но не записывает что агент узнал о проекте. Знания остаются в чате и пропадают.
Три проблемы:
- Нет механизма сбора — ни один шаблон (RF, REVIEW, RES) не требует записывать факты о проекте
- Нет процесса консолидации — tfw-docs работает с architecture decisions и tech debt, но не с фактами из чатов (предпочтения, контекст среды, бизнес-ограничения, забытые требования)
- Нет принудительного напоминания — пользователь может месяцами не запускать tfw-docs, знания накапливаются в артефактах, но не попадают в KNOWLEDGE.md
Вдохновение: Claude Code «dream» — 4-фазный процесс (Orient → Gather → Consolidate → Prune). TFW адаптирует эту идею: сбор через артефакты (не чаты), консолидация через
/tfw-knowledge, mandatory gate каждые N задач.Validated by RESEARCH (RES-TFW-18): Design aligns with Zettelkasten (fleeting→permanent notes), LangMem (hot-path + background consolidation), Claude Code (topic files + index). See RES for full analysis.
2. Текущее состояние (As-Is)¶
Fact collection¶
| Артефакт | Что записывается | Что теряется |
|---|---|---|
| RF §5 Observations | Tech debt (code smells, missing tests) | Факты о проекте: бизнес-контекст, инфра, пользователи, среда |
| REVIEW §3 Tech Debt | Observations → triage | Факты из REVIEW сессии (reviewer видит вещи, которых executor не видел) |
| RES (full doc) | Decisions, open questions | Факты о домене, обнаруженные при исследовании |
| ONB §6 Inconsistencies | Code vs spec | Факты о расхождениях code/spec/reality |
Knowledge consolidation (tfw-docs)¶
| Аспект | Состояние |
|---|---|
| Trigger | After REVIEW or manual |
| Input | RF observations + architecture changes |
| Process | 5-item checklist (arch? decision? deprecated? debt? principle?) |
| Output | KNOWLEDGE.md sections 0-4 + TECH_DEBT.md |
| Missing | No fact collection. No contradiction check. No pruning. No mandatory schedule |
User preferences¶
| Аспект | Состояние |
|---|---|
| File | Не существует |
| Content | Язык, тон, стиль, привычки — нигде не записаны |
| Scope | Cross-project (одна персона, разные проекты) |
Mandatory gate¶
| Аспект | Состояние |
|---|---|
| Current | Нет. tfw-docs запускается когда пользователь вспомнит |
| Pipeline | ⬜ TODO → 📝 HL_DRAFT → ... — ничего до TODO |
3. Целевое состояние (To-Be)¶
3.1 Fact Candidates — сбор в каждом артефакте¶
Каждый агент на финальной стадии пишет раздел «Fact Candidates» — вещи, которые он узнал о проекте, продукте, среде, которые могут быть полезны будущим агентам.
| Артефакт | Кто пишет | Когда |
|---|---|---|
| RF §6 Fact Candidates | Executor | При написании RF |
| REVIEW §5 Fact Candidates | Reviewer | При написании REVIEW |
| RES → Closure | Researcher | При закрытии RES |
Формат:
## Fact Candidates
> Candidates are NOT verified facts. They become facts after `/tfw-knowledge` consolidation.
> Record only if the next agent would make a DIFFERENT DECISION knowing this fact.
>
> Anti-patterns: "project uses git", "code is in Python", "tests exist"
| # | Category | Candidate | Source | Confidence |
|---|----------|-----------|--------|------------|
| 1 | environment | Production DB is on shared instance, not dedicated | User said in chat | High |
| 2 | process | Client expects weekly reports every Monday | Implied from TS constraints | Medium |
| 3 | convention | Team prefers explicit error messages over generic ones | Observed in code review | High |
Категории (domain-agnostic, TFW applies to any field):
| Category | Scope | Examples |
|---|---|---|
environment |
Where the work lives | servers, tools, platforms, classrooms, labs, hosting |
process |
How work gets done | schedules, approvals, reporting cadence, grading rules |
stakeholder |
Who is involved | clients, students, reviewers, partners, regulators |
constraint |
What limits exist | budgets, deadlines, legal, compliance, technical limits |
convention |
Agreed standards | naming, style, format, language, tone |
domain |
Subject matter | business rules, scientific models, curriculum, regulations |
context |
Background knowledge | history, prior decisions, external factors, market conditions |
risk |
Known dangers | fragile dependencies, single points of failure, assumptions |
Categories are open — agents can use custom categories when none fit. The list above is guidance, not exhaustive.
3.2 User Preferences — отдельный файл под .gitignore¶
project-root/
├── .user_preferences.md # ← gitignored, personal
Содержимое: язык общения, тон, стиль работы, привычки, timezone, предпочтения инструментов. Записывается один раз, обновляется агентом если замечает изменения.
3.3 /tfw-knowledge — отдельный workflow (Dream-like consolidation)¶
RESEARCH decision R5: Separate workflow, NOT tfw-docs extension. Different trigger (periodic vs per-task), different duration (10-20 min vs 2 min), different scope (batch vs single).
Новый workflow /tfw-knowledge с 4 фазами:
Phase 1: Orient — прочитать KNOWLEDGE.md + knowledge/ topic files, понять текущее состояние знаний
Phase 2: Gather — собрать Fact Candidates из всех RF/REVIEW/RES с момента последней консолидации
Phase 3: Consolidate — сверить, дедуплицировать, разрешить противоречия, записать в topic files
Phase 4: Prune — удалить устаревшее, пометить непроверенное, обновить индекс в KNOWLEDGE.md §5
Capabilities:
- Fact verification — если факт повторяется в ≥2 артефактах → автоматически «verified». Если один раз → «unverified», агент спрашивает пользователя
- Contradiction detection — если два факта противоречат → агент поднимает вопрос
- Staleness — факты без источника или с источником > N задач назад помечаются для проверки
- Marker — проверенные артефакты маркируются fact-candidates: processed YYYY-MM-DD
- Statistics — обновляет stats в knowledge_state.yaml (total, verified, unverified, rejected)
tfw-docs остаётся как есть — quick per-task pass (sections 0-4 KNOWLEDGE.md). Получает п.6 в checklist: "Fact Candidates present? They will be processed during next /tfw-knowledge."
3.4 Knowledge Gate — отдельный lifecycle¶
Knowledge Gate живёт отдельно от основного pipeline. Не новый статус для задач, а отдельная сессия с собственным трекингом.
Трекинг: .tfw/knowledge_state.yaml
# State — updated by /tfw-knowledge. Config → see tfw.knowledge in PROJECT_CONFIG.yaml
knowledge:
last_consolidation_seq: 15 # seq of last task when consolidation ran
last_consolidation_date: 2026-04-03
stats:
total_facts: 23
verified: 18
unverified: 5
rejected: 2
candidates_processed: 47
sources_scanned: 12
RESEARCH decision R7: No
pending_candidates— seq-based check sufficient.
Lifecycle (2 статуса, своя сессия):
🔍 SCAN → ✅ CONSOLIDATED
🔍 SCAN— агент сканирует все артефакты с моментаlast_consolidation_seq, собирает Fact Candidates✅ CONSOLIDATED— пользователь подтвердил, topic files обновлены,last_consolidation_seqсдвинут
Правила:
- Coordinator проверяет в Phase 0 plan.md: (current_seq - last_consolidation_seq) >= interval
- Gate mode configurable: tfw.knowledge.gate_mode: hard (default) / soft / off
- hard → hard stop: "Knowledge consolidation overdue. Run /tfw-knowledge before proceeding." Skip requires justification
- soft → reminder only, user decides
- Consolidation = отдельная сессия (/tfw-knowledge), 5-10 минут
- Основной pipeline не трогается: никаких новых статусов, никаких pipeline diagram changes
В plan.md: Phase 0: Knowledge Gate Check (перед Phase 1).
3.5 KNOWLEDGE.md + knowledge/ — index + topic files¶
RESEARCH decision R4: Claude Code uses topic files to offload detail from MEMORY.md index. TFW adopts: KNOWLEDGE.md §5 = compact index,
knowledge/= detail.
Структура:
project-root/
├── KNOWLEDGE.md # index (≤200 строк, configurable)
├── knowledge/ # topic files (project-specific facts)
│ ├── environment.md
│ ├── stakeholders.md
│ └── domain.md
├── .tfw/
│ └── knowledge_state.yaml # state + statistics (infrastructure)
KNOWLEDGE.md §5 (compact index):
## 5. Project Facts
> Index of project knowledge. Details in `knowledge/` topic files.
| Category | Count | Topic File |
|----------|-------|------------|
| environment | 7 facts | [→](knowledge/environment.md) |
| stakeholder | 4 facts | [→](knowledge/stakeholders.md) |
| domain | 12 facts | [→](knowledge/domain.md) |
Topic file format (knowledge/environment.md):
# Knowledge: Environment
| # | Fact | Verified | Source(s) | Added |
|---|------|----------|-----------|-------|
| F1 | Production DB on shared PostgreSQL 16 | ✅ 2x | [RF TFW-8](../TFW-8__reviewer_role_and_workflow/RF__PhaseA__core_extraction.md), [RF TFW-12](../TFW-12__scope_budget_centralization/RF__TFW-12__config_centralization.md) | 2026-03-15 |
| F2 | Service lives in Docker Swarm, not K8s | ✅ confirmed | RF SLC-3, RF SLC-7 | 2026-03-20 |
Configurable limits (PROJECT_CONFIG.yaml):
| Parameter | Default | Config key |
|---|---|---|
| KNOWLEDGE.md max lines | 200 | tfw.knowledge.max_index_lines |
| §5 index max lines | 30 | tfw.knowledge.max_index_facts_lines |
| Topic file max facts | 50 | tfw.knowledge.max_facts_per_topic |
| Topic files max count | 8 (soft) | tfw.knowledge.max_topic_files |
| Consolidation interval | 5 | tfw.knowledge.interval |
| Gate mode | hard | tfw.knowledge.gate_mode |
4. Фазы¶
Phase A: Fact Candidates — templates + collection mechanism 🔴¶
- Добавить §6 Fact Candidates в RF.md template (mandatory)
- Добавить §5 Fact Candidates в REVIEW.md template (mandatory)
- Добавить Fact Candidates в RES.md Closure section (mandatory)
- Добавить quality filter в template: "Would the next agent decide differently?"
- Добавить mindset reminders в handoff.md, research.md, review.md
- Создать
.user_preferences.mdtemplate +.gitignoreentry в init.md - Обновить conventions.md (Fact Candidates definition, categories)
- Обновить glossary.md (new terms)
Phase B: /tfw-knowledge workflow + knowledge infrastructure 🔴¶
- Создать
.tfw/workflows/knowledge.md— 4-phase process (Orient → Gather → Consolidate → Prune) - Создать
knowledge/папку с template topic file - Добавить §5 Project Facts (compact index) в KNOWLEDGE.md template
- Создать
.tfw/knowledge_state.yaml - Добавить
tfw.knowledgesection в PROJECT_CONFIG.yaml (limits + gate_mode) - Обновить tfw-docs checklist (п.6: Fact Candidates marker)
- Обновить conventions.md (новые файлы: knowledge.md workflow, knowledge_state.yaml, knowledge/ folder)
- Обновить glossary.md (Knowledge Gate, Consolidation, Topic File)
- Обновить adapters (Antigravity + Claude Code)
Phase C: Knowledge Gate — plan.md integration 🟡¶
- Добавить Phase 0: Knowledge Gate Check в plan.md
- Обновить plan.md adapters (Antigravity + Claude Code)
Future TODOs (к записи в Task Board)¶
tfw-config— пропагация yaml config changes во все workflows/adapterstfw-user-tune— personal preferences pipeline (.user_preferences.md lifecycle)
5. Definition of Done (DoD)¶
- ✅ 1. RF.md template: §6 Fact Candidates section (mandatory)
- ✅ 2. REVIEW.md template: §5 Fact Candidates section (mandatory)
- ✅ 3. RES.md template: Fact Candidates in Closure (mandatory)
- ✅ 4. Quality filter in template: "Would the next agent decide differently?"
- ✅ 5. Mindset reminders in handoff.md, research.md, review.md
- ✅ 6.
.user_preferences.mdtemplate exists,.gitignoreguidance in init workflow - ✅ 7.
.tfw/workflows/knowledge.md— 4-phase consolidation workflow - ✅ 8.
knowledge/folder with topic file template - ✅ 9. KNOWLEDGE.md template: §5 compact index with links to topic files
- ✅ 10.
.tfw/knowledge_state.yamlwith stats tracking - ✅ 11.
tfw.knowledgesection in PROJECT_CONFIG.yaml (limits + gate_mode) - ✅ 12. tfw-docs checklist updated (p.6: Fact Candidates marker)
- ✅ 13. plan.md: Phase 0 Knowledge Gate Check before Phase 1
- ✅ 14. glossary.md: new terms (Fact Candidate, Knowledge Gate, Consolidation, Topic File)
- ✅ 15. All adapters synced (Antigravity + Claude Code)
- ✅ 16. No changes to main pipeline diagrams (separate lifecycle)
6. Definition of Failure (DoF)¶
- ❌ 1. Fact Candidates section = empty «No candidates» в каждом RF (агенты игнорируют)
- ❌ 2. DOCS gate becomes bureaucracy — 10 minutes of user time every 5 tasks с нулевой ценностью
- ❌ 3. tfw-docs consolidation раздувает KNOWLEDGE.md до нечитаемого размера (>300 строк)
- ❌ 4. Агенты записывают trivial facts («project uses git»)
При провале: - DoF-1: Усилить примерами в шаблоне, добавить anti-pattern «No candidates» в review checklist - DoF-2: Сделать gate soft (recommendation) вместо hard - DoF-3: Ввести лимит на §5 (≤30 facts) + pruning phase - DoF-4: Добавить quality criteria в template
7. Принципы¶
- Facts ≠ Observations — Observations = tech debt (code issues). Facts = project knowledge (бизнес, инфра, среда, стейкхолдеры). Два разных типа информации, два разных pipeline'а.
- Candidates ≠ Facts — Agents записывают кандидатов. Они становятся фактами только после consolidation (tfw-docs). Один источник = unverified. Два+ = verified.
- Dream, not database — Цель не собрать все факты, а собрать полезные. Quality > quantity. Факт полезен если будущий агент принял бы другое решение, зная его.
- Gate protects quality — Knowledge Gate защищает от drift: знания накапливаются в артефактах, но не попадают в KNOWLEDGE.md. Gate = принудительная синхронизация. Отдельный lifecycle — не трогает основной pipeline.
- Preferences are personal —
.user_preferences.md= gitignored, personal, cross-project applicable. Project facts = shared, committed, project-specific. - Domain-agnostic categories — TFW работает в образовании, бизнесе, инженерии, дизайне, науке. Категории фактов должны быть универсальными:
environment,process,stakeholder, неinfra,integration,deployment. - Configurable by design — Лимиты, gate mode, interval — всё в PROJECT_CONFIG.yaml. Defaults (разумные) + override (под проект).
8. Зависимости¶
| Зависимость | Статус |
|---|---|
| RF.md template | ✅ current |
| REVIEW.md template | ✅ current |
| RES.md template | ✅ current |
| docs.md workflow | ✅ current |
| KNOWLEDGE.md template | ✅ current |
| conventions.md | ✅ current |
| glossary.md | ✅ current |
| plan.md | ✅ current (v0.5.5) |
9. Риски¶
| Риск | Вероятность | Влияние | Mitigation |
|---|---|---|---|
| Fact Candidates = noise (too many trivial facts) | Высокая | Среднее | Quality examples in template + pruning in consolidation |
| DOCS gate friction | Средняя | Высокое | Make it lightweight (scan → propose → approve, <5 min) |
| KNOWLEDGE.md grows unbounded | Средняя | Среднее | Prune phase + size limit (≤30 facts in §5) |
| Blast radius concerns | ~~Средняя~~ Низкая | ~~Среднее~~ Низкое | Knowledge Gate = separate lifecycle, no pipeline changes. Only plan.md gets Phase 0 check |
| Contradiction resolution = hard | Низкая | Среднее | Agent flags, user resolves — no auto-resolution |
HL — TFW-18: Knowledge Consolidation | 2026-04-03