forgeplan_discover_finding

Добавляет один обнаруженный факт в активную сессию исследования. После того как forgeplan_discover_start возвращает протокол, агент проходит каждую фазу (detect / structure / code / git / tests / docs), читает файлы в предписанном порядке уровней и вызывает этот инструмент один раз для каждого наблюдения, которое стоит зафиксировать. ForgePlan материализует каждый обнаруженный факт как реальный артефакт (Note / PRD / RFC / ProblemCard / Evidence), чтобы они сохранялись после сессии и оставались доступными для запросов.

Категория: Обнаружение в Brownfield

Только MCP по замыслу. Этот инструмент не имеет эквивалента в forgeplan CLI. Протокол исследования управляется агентом - ForgePlan не читает исходные файлы самостоятельно. Оператор-человек, используя CLI, запускает сессию, а затем запускает агента; обнаруженные факты возвращаются только через MCP.

Когда агент вызывает этот инструмент

• После прочтения исходного файла и выявления шаблона, зависимости, границы или странности, которые стоит зафиксировать.
• После анализа git log и обнаружения отката, коммита с решением или заброшенной ветки.
• После запуска тестов и обнаружения поведенческого контракта, который не был явно выражен в самом коде.
• После сверки README.md с кодом и обнаружения расхождений (обнаруженный факт становится артефактом ProblemCard).

Уровни источников (напоминание)

Каждый обнаруженный факт должен содержать уровень, из которого он получен, чтобы последующий синтез мог его взвесить:

Уровень	Класс источника	Типичный вид
1	Исходный код	Note, RFC, Evidence
2	История Git	Note, Evidence
3	Тесты	Evidence
4	Документация	Note, ProblemCard (при расхождении)

Входные параметры

Имя	Тип	Обязательный	Описание
session_id	string	yes	Дескриптор сессии, возвращённый forgeplan_discover_start.
phase	string	yes	Одна из фаз: detect, structure, code, git, tests, docs, synthesize.
tier	integer	yes	Уровень источника 1, 2, 3 или 4 (см. таблицу выше).
kind	string	yes	Тип создаваемого артефакта: Note / PRD / RFC / ProblemCard / Evidence.
title	string	yes	Краткий, конкретный заголовок для обнаруженного факта (используется как заголовок артефакта).
body	string	yes	Тело в формате Markdown. Включите: что вы наблюдали, где (файл:строка) и почему это важно.
source_files	string[]	no (по умолчанию: [])	Пути, которые послужили основой для обнаруженного факта. Записываются, чтобы рецензенты могли проследить.

Источник схемы: crates/forgeplan-mcp/src/server.rs::DiscoverFindingParams

Возвращает

Идентификатор созданного артефакта плюс подтверждение того, что он был связан с сессией исследования:

{
  "artifact_id": "NOTE-087",
  "session_id": "discover-legacy-billing-service-2026-04-11T10:15:00Z",
  "phase": "code",
  "tier": 1,
  "linked": true
}

Артефакт помечается тегами discover:<session_id> и tier:<n>, чтобы forgeplan_discover_complete мог группировать обнаруженные факты для этапа синтеза.

Пример вызова

{
  "session_id": "discover-legacy-billing-service-2026-04-11T10:15:00Z",
  "phase": "code",
  "tier": 1,
  "kind": "note",
  "title": "Billing engine uses two overlapping retry layers",
  "body": "`src/billing/retry.rs` and `src/http/client.rs` both implement exponential backoff. The outer layer wraps the inner, producing effective delays of retry_inner × retry_outer on transient failures. Likely accidental - worth a RFC before any reliability work.",
  "source_files": ["src/billing/retry.rs", "src/http/client.rs"]
}

Типичная последовательность

discover_start → (many) discover_finding → discover_complete

Агенты обычно создают 10–40 обнаруженных фактов за одну сессию исследования. Жёсткого ограничения нет; фиксируйте один обнаруженный факт на одно конкретное наблюдение, а не объединяйте несколько проблем в одну.

Эквивалент CLI

Нет - намеренно. Обнаруженные факты исследования передаются только через путь MCP.

См. также

• Обзор MCP
• forgeplan_discover_start - протокол, который является источником этого инструмента
• forgeplan_discover_complete - синтезирует обнаруженные факты в предложения
• forgeplan_new - альтернатива для создания артефактов вне сессии