Synth Nova Manifest

ADR-0011: Integration Triage Policy

3 min read

ADR-0011: Integration Triage Policy

Status

accepted

Context

В планировании Week 4.7 (bugfix sprint) возник вопрос: включать ли Tavily (search provider) integration. Первоначальная интуиция “звучит полезно” привела к estimate 4-6h работы и риску для stabilization sprint. Pre-check показал, что текущий web_search — Anthropic server-side tool, и Tavily потребует client-side handler, изменений в промптах, ролях, cost tracking и тестах — то есть MEDIUM RISK, а не drop-in.

Эта ситуация выявила системную проблему: integration decisions принимаются интуитивно (“seems useful”), а не через структурированный фильтр. Без policy подобные решения будут повторяться — и каждый раз есть риск derail-нуть bugfix sprint “маленьким” добавлением. Параллельно растёт список потенциальных кандидатов (Tavily, Exa, FMP, Firecrawl, SimilarWeb, SEMrush, Composio) без явных trigger conditions для каждого.

Decision

Принят формальный Integration Triage Policy (IntegrationTriagePolicy в 00-Core/):

  1. Pain-point-driven: integration не добавляется без observed pain point (3-5 реальных наблюдений из FEEDBACK_LOG.md или failed runs).
  2. Pain point dictates category: weak recall → search providers; absurd financial выводы → finance APIs; missing capability → orchestration; и т.д.
  3. Risk classification (LOW / MEDIUM / HIGH) определяет, в каком sprint допустимо merge: bugfix sprints принимают только LOW.
  4. Hypothesis + success metric обязательны до A/B evaluation.
  5. Candidates table — living document со статусом каждого deferred integration и его trigger condition.

Alternatives Considered

Option A: Ad-hoc decisions per integration

  • Pros: максимальная гибкость, нет process overhead.
  • Cons: “seems useful” — типичная мотивация, sprint derailing предсказуем; нет traceability “почему добавили X”; повторение тех же дискуссий.

Option B: Strict “no integrations outside dedicated integration sprint”

  • Pros: гарантия что bugfix/capability sprints не размываются; чёткое окно для всех integration decisions.
  • Cons: блокирует legitimate LOW RISK drop-in improvements (например замена сломанного API на эквивалентный); требует ждать sprint cycle для тривиальных swaps.

Option C: Pain-point-driven triage with risk classification ← chosen

  • Pros: баланс дисциплины и гибкости; LOW RISK не блокируется; MEDIUM/HIGH явно отложены до evidence; решения traceable к конкретному pain point; candidates table даёт обзор того, что отложено и почему.
  • Cons: требует disciplined classification (риск что-то отнести к LOW когда оно MEDIUM); требует поддержания candidates table.
  • Why chosen: прямо адресует наблюдённую проблему (Tavily было бы добавлено по интуиции), но не превращается в bureaucratic gate для очевидных drop-in замен. Risk taxonomy уже валидирована на Week 4.7 pre-check.

Consequences

Positive:

  • Future integration decisions traceable к specific pain point (не “звучит полезно”).
  • Candidates table становится living document с trigger condition для каждого deferred integration.
  • FEEDBACK_LOG.md (external testers) получает чёткую роль primary evidence source для Rule 3.
  • Disagreements об integrations резолвятся через rule, а не opinion.
  • Tavily, Exa, FMP, Firecrawl, SimilarWeb, SEMrush, Composio задокументированно отложены с reasons.

Negative / Trade-offs:

  • Дополнительный шаг (классификация risk + проверка evidence) перед integration работой.
  • Риск классифицировать MEDIUM как LOW и всё равно derail-нуть sprint.
  • Candidates table может устаревать, если её не пересматривать.

Mitigations:

  • Risk classification примеры зафиксированы в самой policy (Rule 2) — не нужно изобретать каждый раз.
  • Quarterly review цикл candidates table (Rule: review после каждого 5-го capability sprint или если list >10).
  • Pre-check pattern (как Week 4.7 для Tavily) — обязательная 10-минутная разведка перед классификацией.

Follow-ups

  • Создать reports/streamlit_runs/FEEDBACK_LOG.md в synth-brain (если ещё нет) как primary evidence source для Rule 3.
  • При первом MEDIUM RISK integration — провести pre-check по шаблону Week 4.7 Tavily.
  • Через 2 квартала пересмотреть candidates: если кандидат “deferred” без trigger fire — рассмотреть removal.
  • Если candidates table вырастет >10 — провести review cycle.

References

  • IntegrationTriagePolicy — full policy text (00-Core).
  • Decision-Log — индекс всех ADR.
  • EscalationPolicy — related operational policy.
  • DecisionRights — кто принимает integration decisions.
  • Week 4.7 pre-check (Tavily) — пример MEDIUM RISK классификации, послуживший trigger для policy.

Graph View

Backlinks