trace-first-starter

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). Но вызвать его можно:

Из plan.md — координатор говорит “рекомендую RESEARCH”, пользователь подтверждает, координатор запускает research.md inline (как подпроцесс plan)
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 вопроса оказался эффективнее, это стоило зафиксировать раньше.

This site is open source. Improve this page.