RES — TFW-11: RESEARCH Stage¶
Дата: 2026-03-30 Автор: Coordinator (AI) Статус: 🔬 RES — В процессе Parent HL: HL-TFW-11
Контекст исследования¶
Проектируем стадию RESEARCH для TFW-пайплайна: артефакт, воркфлоу, шаблон, интеграцию. Нужно определить внутреннюю структуру RESEARCH-процесса, формат цикла, и конкретные секции RES-шаблона.
Решения¶
| # | Решение | Обоснование |
|---|---|---|
| D1 | RES-артефакт: summary сверху + лог этапов ниже (вариант C) | Удобно для AI (быстрый доступ к решениям) + полный trace |
| D2 | Standalone RESEARCH создаёт мини-задачу TFW-N |
Единообразие: всё в tasks/, всё на Task Board |
| D3 | Standalone lifecycle: → 🔬 RES → ✅ DONE (или → новая задача) | Нет HL для standalone; если нужна работа — отдельная задача |
| D4 | Role lock: Coordinator | RESEARCH = исследование, не исполнение |
| D5 | TS ссылается на HL + RES | RES дополняет HL, не заменяет |
| D6 | Max 3 вопроса за раз | 5 — слишком разнородно, теряется фокус |
| D7 | RES создаётся сразу при входе в RESEARCH | Пользователь читает параллельно, агент пишет по ходу |
| D8 | 3 этапа: Сбор, Извлечение, Вызов | Академическая аналогия: lit review → data collection → analysis. Покрывает все виды работ |
| D9 | Этапы = чеклист, не строгая последовательность | Агент покрывает все три, порядок по ситуации |
| D10 | Checkpoint после каждого этапа | 3 точки решения вместо одной — раннее закрытие возможно |
| D11 | Терминология: Этап (Stage) + Проход (Pass), без "цикл" | Этап = тематический блок, Проход = все этапы. Просто и однозначно |
| D12 | Один воркфлоу research.md, два входа | Plan inline + standalone /tfw-research. Единая реализация |
| D13 | Read-only AG: лимиты автономной работы | Мягкие: ≤5 веб, ≤15 файлов/этап. Жёсткий: ≤3 вопроса/этап |
| D14 | Настройки RESEARCH в отдельном файле | Все лимиты и параметры в одном месте, легко тюнить |
| D15 | Anti-complexity check — обязательная проверка на переусложнение | См. Цикл 6 |
| D16 | Заключение (Conclusion) в RES — один абзац, самокритично | Итог сессии: что сделано, какая польза |
Открытые вопросы¶
| # | Вопрос | Статус | Ответ |
|---|---|---|---|
| Q1 | Внутренняя структура RESEARCH: какие этапы? | ✅ | 3 этапа: Сбор → Извлечение → Вызов (чеклист, не строгая последовательность) |
| Q2 | Что такое "цикл" формально? | ✅ | Этап (Stage) = один тематический блок. Проход (Pass) = round-trip по всем этапам. Min 1 проход. |
| Q3 | Read-only автономия агента в RESEARCH | ✅ | Read-only AG: читает код/веб, пишет только в RES. См. D13 для лимитов. |
| Q4 | Inline в plan.md или отдельный /tfw-research |
✅ | Один воркфлоу research.md, два входа (plan inline + standalone) |
| Q5 | Секции RES-шаблона (финальные) | 🔬 Обсуждаем | См. Цикл 5 |
| Q6 | Checkpoint после каждого этапа — формат? | 🔬 Обсуждаем | См. Цикл 5 |
| Q7 | Лимиты автономной работы | ✅ | См. D13 |
Цикл 1: Базовые решения¶
Закрыты D1-D5. Определены: вариант C для артефакта, standalone = мини-задача, Coordinator lock, TS→HL+RES.
Цикл 2: Детали реализации¶
Закрыты D6-D7. Открыты Q1-Q5 — структура RESEARCH-процесса, цикл, автономия, интеграция.
Цикл 3: Внутренняя структура RESEARCH¶
Анализ: как устроен research в разных контекстах¶
Пользователь предложил разделить RESEARCH на именованные этапы. Аналогия с академическим research:
| Академический research | TFW-аналог | Что происходит |
|---|---|---|
| Literature review / Related works | Обзор | Внешние источники: документация, блоги, issues, версии библиотек, аналогичные решения |
| Data collection | Извлечение | Внутренние источники: код проекта, соседние проекты, знания в голове пользователя |
| Analysis & Hypotheses | Анализ | Альтернативы, слепые зоны, edge cases, критика, неожиданные сценарии |
Но академический research — линейный. TFW — итеративный. Вопрос: этапы строго последовательные или агент выбирает порядок?
Предложение: 3 этапа RESEARCH¶
Этап 1: Сбор — "Что мы НЕ знаем?" - Агент анализирует HL и определяет информационные пробелы - Автономный поиск: документация, changelog'и, issues, blog posts - Вопросы к пользователю: "Есть ли X? Пробовали ли Y? Какая версия Z?" - Результат: закрытые пробелы, найденные факты
Этап 2: Извлечение — "Что мы НЕ ВИДИМ?" - Агент изучает проект: код, артефакты, конфиги, паттерны - Вопросы к пользователю: "Я вижу X в коде — это намеренно?", "Есть контекст, который не в проекте?" - Скрытые знания: то, что пользователь знает но не передал - Результат: вытащенный контекст, неявные требования
Этап 3: Вызов — "Что мы НЕ ОЖИДАЕМ?" - Альтернативные подходы: "А если не X, а Y?" - Слепые зоны: edge cases, нетипичные сценарии - Критика решений из HL: что может пойти не так - Неожиданные пересечения: "Это похоже на проблему Z, которую обычно решают через..." - Результат: проверенные/отвергнутые альтернативы, новые риски
Три вопроса к тебе:¶
Q1: Порядок этапов. Я предложил: Сбор → Извлечение → Вызов. Логика: сначала собираем факты, потом вытаскиваем скрытое, потом критикуем имея полную картину. Но можно иначе — например, начать с Вызова, чтобы сразу вскрыть слабые места HL, и только потом собирать информацию прицельно. Как тебе кажется правильнее?
Q2: Жёсткость этапов. Три этапа — это: (A) строгая последовательность, каждый формально закрывается; (B) рекомендуемый порядок, агент может перемешивать по ситуации; (C) чеклист — агент должен покрыть все три, но в любом порядке и не обязательно отдельными блоками?
Q3: Checkpoint — после каждого этапа или только в конце полного прохода? Если после каждого — получаем 3 точки принятия решения ("хватит собирать? хватит извлекать? хватит критиковать?"). Если в конце — один checkpoint на весь проход, но он более весомый.
Checkpoint 3¶
| Область | Покрыто? |
|---|---|
| Базовые решения (D1-D7) | ✅ |
| Этапы RESEARCH (D8-D10) | ✅ Сбор → Извлечение → Вызов, чеклист, checkpoint после каждого |
Цикл 4: Определение цикла, автономия, интеграция¶
Что такое "цикл" — формализация¶
Имеем 3 этапа, каждый с checkpoint. Но "минимум 3 цикла" (D6 from HL) — это 3 этапа или 3 полных прохода по всем этапам?
Предложение — переопределить терминологию:
- Этап (Stage) = Сбор / Извлечение / Вызов — один тематический блок
- Проход (Pass) = один full round-trip по всем непокрытым этапам
- Цикл (Cycle) = этап + ответы пользователя + обновление RES
Минимум: агент обязан покрыть все 3 этапа (= 3 цикла минимум). Checkpoint после каждого этапа позволяет пользователю сказать "этот этап закрыт" или "копаем глубже". Если после первого прохода остались открытые вопросы — второй проход по нужным этапам.
Итого: минимум 3 цикла = минимум 1 полный проход по 3 этапам. Может быть больше, если пользователь хочет углубиться.
Автономия агента — конкретика по этапам¶
| Этап | Автономные действия (без спроса) | Требует подтверждения |
|---|---|---|
| Сбор | Веб-поиск, чтение документации, поиск issues/changelogs | — |
| Извлечение | Чтение кода проекта, grep, анализ артефактов | Чтение соседних проектов (может быть приватно) |
| Вызов | Анализ и рассуждения на основе собранного | — |
Во всех этапах: запись только в RES-файл. Никаких других файлов. Никакого кода.
Это "read-only AG" — агент автономно собирает информацию, но единственный side-effect — обновление RES-артефакта. Формально: CL-режим с расширенными read-правами.
Интеграция: inline vs отдельная команда¶
Аргументы за inline (research прямо в plan-сессии): - Один контекст, нет переключения - Координатор уже загрузил всю информацию - Естественный flow: HL → "нужен research?" → research → TS
Аргументы за отдельный /tfw-research:
- Чистое разделение ответственности
- Standalone нужен в любом случае
- Можно вызвать повторно без перезапуска plan
Компромиссное предложение: одна реализация, два входа.
/tfw-research — единственный воркфлоу (research.md). Но вызвать его можно:
1. Из plan.md — координатор говорит "рекомендую RESEARCH", пользователь подтверждает, координатор запускает research.md inline (как подпроцесс plan)
2. Standalone — пользователь вызывает /tfw-research напрямую
Разница только в контексте входа: - Из plan: уже есть HL, задача, папка - Standalone: воркфлоу сам создаёт задачу/папку
Три вопроса:¶
Q1: Терминология. Этап/Проход/Цикл — понятно? Или лучше другие названия? Может проще: этап = stage, а "цикл" вообще убрать и говорить "проход"?
Q2: Автономия. Read-only AG с записью только в RES — согласен? Нужно ли ограничение на количество веб-запросов или время автономной работы?
Q3: Один воркфлоу, два входа. Подходит? Или всё-таки хочешь жёстко разделить pipeline-research и standalone-research?
Checkpoint 4¶
| Область | Покрыто? |
|---|---|
| Базовые решения (D1-D12) | ✅ |
| Терминология | ✅ Этап + Проход |
| Автономия | ✅ Read-only AG, лимиты → Цикл 5 |
| Интеграция | ✅ Один воркфлоу, два входа |
Цикл 5: Лимиты, формат checkpoint, RES-шаблон¶
Лимиты автономной работы (D13)¶
RESEARCH — не бесконечный процесс. Нужны ограничения, но мягкие (рекомендательные, не блокирующие).
| Параметр | Лимит | Тип | Обоснование |
|---|---|---|---|
| Веб-запросы за этап | ≤ 5 | Мягкий | Достаточно для целевого поиска, не превращается в crawling |
| Файлов проекта прочитано за этап | ≤ 15 | Мягкий | Агент должен читать прицельно, не сканировать весь проект |
| Вопросов к пользователю за этап | ≤ 3 | Жёсткий | D6 — уже решено |
| Проходов (passes) | Min 1, рекомендуемый max 3 | Мягкий | После 3 проходов — настоятельная рекомендация сворачивать |
Превышение мягких лимитов: агент сообщает пользователю и продолжает, если пользователь подтвердит.
Формат checkpoint после этапа¶
Каждый этап завершается мини-отчётом в RES:
### Checkpoint: Сбор
| Что найдено | Что осталось |
|-------------|-------------|
| Факт 1 | Пробел 1 |
| Факт 2 | — |
**Оценка агента:** [одно предложение — хватает ли информации по этому этапу]
**Рекомендация:** закрыть этап / углубиться в [конкретная тема]
→ Решение пользователя: ___
Ключевое: агент всегда даёт рекомендацию, но решает пользователь.
RES-шаблон — финальный драфт¶
На основе всех решений D1-D13:
# RES — {PREFIX}-{N}: {Title}
> **Дата**: YYYY-MM-DD
> **Автор**: {author}
> **Статус**: 🔬 RES — В процессе / Завершён
> **Parent HL**: [HL-{PREFIX}-{N}](path) (если pipeline)
> **Режим**: Pipeline / Standalone
---
## Контекст исследования
Одним абзацем: что исследуем и зачем.
## Решения
| # | Решение | Обоснование |
## Открытые вопросы
| # | Вопрос | Статус | Ответ |
---
## Этап: Сбор — "Что мы НЕ знаем?"
{автономный поиск, факты, пробелы, вопросы к пользователю}
### Checkpoint: Сбор
| Что найдено | Что осталось |
→ Решение пользователя: ___
## Этап: Извлечение — "Что мы НЕ ВИДИМ?"
{анализ проекта, скрытые знания, вопросы к пользователю}
### Checkpoint: Извлечение
| Что найдено | Что осталось |
→ Решение пользователя: ___
## Этап: Вызов — "Что мы НЕ ОЖИДАЕМ?"
{альтернативы, слепые зоны, критика, edge cases}
### Checkpoint: Вызов
| Что найдено | Что осталось |
→ Решение пользователя: ___
---
## Итоговый checkpoint
| Этап | Статус | Ключевые находки |
|------|--------|-----------------|
| Сбор | ✅/🔬 | ... |
| Извлечение | ✅/🔬 | ... |
| Вызов | ✅/🔬 | ... |
**Вердикт:** Достаточно для TS / Нужен ещё проход
Три вопроса:¶
Q1: Лимиты. Таблица выше — адекватные значения? Или что-то нужно жёстче/мягче? Особенно: 5 веб-запросов за этап и 15 файлов — не мало?
Q2: Checkpoint формат. Таблица "найдено/осталось" + рекомендация + решение пользователя — достаточно? Или нужно больше структуры?
Q3: RES-шаблон. Этот драфт — готов как основа для .tfw/templates/RES.md? Что добавить/убрать?
Checkpoint 5¶
| Область | Покрыто? |
|---|---|
| Все решения D1-D13 | ✅ |
| Лимиты | ✅ |
| Формат checkpoint | ✅ |
| RES-шаблон (базовый) | ✅ |
Цикл 6: Настройки, anti-complexity, заключение¶
Где хранить настройки RESEARCH (D14)¶
Сейчас PROJECT_CONFIG.yaml уже содержит tfw: и build: секции. Два варианта:
A: Добавить research: секцию в PROJECT_CONFIG.yaml
research:
web_queries_per_stage: 5
files_read_per_stage: 15
questions_per_stage: 3
max_passes: 3
B: Отдельный .tfw/research_config.yaml
Плюс: research — самостоятельный модуль, конфиг может быть большим.
Рекомендация: A — PROJECT_CONFIG.yaml уже задуман как единое место для параметров проекта. Research — часть проекта. Отдельный файл оправдан, только если настроек станет 20+. Сейчас их 4. Если вырастет — вынесем.
Anti-complexity: куда и как¶
Три варианта размещения:
A: Отдельный 4-й этап "Упрощение" - После Сбора, Извлечения, Вызова — ещё один этап - Плюс: явный, не пропустишь - Минус: добавляет вес процессу (ирония — anti-complexity добавляет complexity)
B: Обязательный вопрос в итоговом checkpoint - После всех этапов, перед вердиктом "достаточно для TS" - Агент обязан задать: "Не переусложнили ли мы решение? Можно ли сделать проще при наших обстоятельствах?" - Плюс: не утяжеляет этапы, ловит момент "полной картины" - Минус: один вопрос может быть поверхностным
C: Часть этапа "Вызов" - Вызов уже про критику — добавить обязательный пункт про сложность - Плюс: органично вписывается - Минус: может затеряться среди других вопросов Вызова
Рекомендация: B — итоговый checkpoint. Причина: anti-complexity проверка имеет смысл только когда вся картина собрана. В середине исследования рано судить о сложности. В итоговом checkpoint агент видит все решения (таблица D1-DN) и может оценить целое.
Формат в RES-шаблоне:
## Итоговый checkpoint
...таблица этапов...
### Проверка на сложность
**Вопрос:** Соразмерно ли решение задаче? Что можно убрать без потери ценности?
**Оценка агента:** [конкретный ответ — что избыточно, что оставить]
→ Решение пользователя: ___
**Вердикт:** Достаточно для TS / Нужен ещё проход
Заключение (D16)¶
Добавляем в конец RES-шаблона:
## Заключение
[Один абзац. Что исследовано. Какие ключевые решения приняты.
Что дал RESEARCH, чего бы не было без него.
Самокритика: что можно было сделать лучше.]
Три вопроса:¶
Q1: Настройки — в PROJECT_CONFIG.yaml (секция research:) или отдельный файл?
Q2: Anti-complexity — итоговый checkpoint (вариант B) подходит? Или хочешь отдельный этап?
Q3: Достаточно ли информации для TS? Мы закрыли: структуру этапов, терминологию, артефакт, шаблон, лимиты, автономию, интеграцию, настройки, anti-complexity, заключение. Осталось: драфт research.md воркфлоу и обновление conventions/glossary — но это уже работа для TS, не для RESEARCH. Готовы сворачивать?
Checkpoint 6¶
| Область | Покрыто? |
|---|---|
| Решения D1-D16 | ✅ Все подтверждены |
| Настройки RESEARCH | ✅ PROJECT_CONFIG.yaml секция research: |
| Anti-complexity | ✅ Обязательный вопрос в итоговом checkpoint |
| Готовность к TS | ✅ Готовы |
Итоговый checkpoint¶
| Этап | Статус | Ключевые находки |
|---|---|---|
| Сбор | ✅ | Академическая аналогия (lit review → analysis), 3 этапа, терминология Stage/Pass |
| Извлечение | ✅ | Существующий plan.md Phase 1 слишком поверхностный; RES = живой документ с самого начала; настройки в PROJECT_CONFIG |
| Вызов | ✅ | Anti-complexity check обязателен; standalone = мини-задача; один воркфлоу два входа |
Проверка на сложность¶
Вопрос: Соразмерно ли решение задаче? Что можно убрать без потери ценности? Оценка агента: Решение адекватно. 3 этапа — минимальная полезная структура, не 7 и не 10. Лимиты мягкие — не блокируют, но направляют. Единственный риск переусложнения: сам RES-шаблон может оказаться громоздким для тривиальных исследований — но standalone мини-задачи и skip-path в pipeline это компенсируют. Убирать нечего.
Вердикт: Достаточно для TS.
Заключение¶
За 6 циклов RESEARCH определена полная архитектура новой стадии: 3 именованных этапа (Сбор/Извлечение/Вызов) как чеклист, RES-артефакт с живыми таблицами решений и вопросов, read-only автономия агента, единый воркфлоу с двумя входами (pipeline + standalone), настройки в PROJECT_CONFIG, anti-complexity guard в итоговом checkpoint. Без RESEARCH мы бы пропустили вопрос standalone-размещения (мини-задачи vs отдельная папка), формализацию этапов и проблему разброса настроек по файлам. Самокритика: первые циклы по 5 вопросов были избыточны — формат 3 вопроса оказался эффективнее, это стоило зафиксировать раньше.