---

sparc_phase: S project: pediatric-news created: 2026-05-11 author: claude-vps status: draft

Specification — Pediatric News (Telegram + Threads + Infographic)

Контекст і мотивація

Pediatric News — власне експертне медіа Deltamedical у Telegram-каналі @smart_pediatric_news. Поточна pipeline (3×/день, ~85+ постів за 4 тижні, ~10% fail-rate через Gemini-timeout) обмежена single-channel текстом. Pivot 2026-05-11: додаємо два паралельні output'и на той самий вхід — Threads-thread (root + 2-3 self-reply) і square infographic (PIL-render). Мета — органічний охват серед педіатрів-практиків та батьків через Threads + візуальна якість постів у Telegram.

Цілі (Goals)

• [ ] 3 публікації/день у Telegram із success-rate ≥ 95% (зараз ~90%; реалізувати retry для Gemini-timeout)
• [ ] 1 Threads-thread/день з depth=3 (root + 2 reply), кожен пост ≤500 знаків, ROOT без link
• [ ] 1 infographic PNG (1080×1080) на кожен Telegram-пост, прикріплена як photo+caption замість text-only
• [ ] Дедуплікація — один RSS-article обробляється лише раз, незалежно від каналу
• [ ] Логи й метрики: успіх/помилка кожного fan-out по 3-х каналах у JSON-log + щоденний summary
• [ ] Token refresh-flow для Threads (long-lived 60 днів) задокументований і алертовий за 7 днів до expiry

Не цілі (Non-goals)

• TikTok / Instagram Reels / YouTube Shorts (HOLD — AI-відео дороге)
• B2B-комунікація з лікарями (медпредставники окремо)
• Пряма реклама брендів Deltamedical у постах
• Перепис існуючої Telegram-pipeline на Node.js (AGENTS.md — застаріле)
• Approval-workflow з людиною-редактором (повна автоматизація залишається)

Користувачі / стейкхолдери

• Primary: педіатри-практики UA — споживають у Telegram + Threads (фаховий tone, термінологія, HR/CI)
• Secondary: батьки школярів/малюків — Threads-bonus, впливають на вибір теми (не tone)
• Owner: Сергій — продуктові рішення, метрики
• SMM: Настя — моніторинг охватів, контент-якості

Вимоги (Requirements)

Функціональні

• FR1: RSS-fetch з 5 джерел (AAP, JAMA Pediatrics, Lancet Child, BMJ, Nature PR), вікно 90 годин
• FR2: Gemini обирає 1 найважливішу статтю → HTML-форматований Telegram-пост
• FR3: threads-news-editor agent трансформує той самий source у root + 2 reply (≤500 chars кожен)
• FR4: infographic-builder skill → JSON spec → PIL render → PNG 1080×1080
• FR5: Telegram publish (sendPhoto + caption HTML); Threads publish (3 sequential, 30-60 сек пауза)
• FR6: seen_ids.json — атомарне записування ПІСЛЯ успіху всіх 3 каналів (або partial-success policy)

Нефункціональні

• NFR1 (performance): один cron-tick ≤ 180 сек end-to-end (Gemini ≤60 + Threads 3×15 + render ≤10)
• NFR2 (reliability): retry 1× на Gemini timeout, 2× на Telegram/Threads API 5xx
• NFR3 (compliance): джерела з посиланнями, без претензій на «лікування»; PNG не містить brand-claims
• NFR4 (security): токени тільки з /srv/passepartout/ (telegram, meta/threads, google/gemini)

Edge cases

• Що робити якщо Gemini timeout: retry 1× з зменшеним batch (15→8 статей)
• Що робити якщо Threads reply падає (permission error як 2026-05-11): логуємо, Telegram+infographic вже опубліковані, не блокуємо
• Що робити якщо RSS feed порожній/down: пропускаємо джерело, continue з решти
• Що робити якщо PNG render fail: fallback на text-only Telegram-пост

Метрики успіху

• Telegram success-rate: 90% → 95% (за 14 днів після deploy)
• Threads daily posts: 0 → 1/день з depth=3 (за 7 днів)
• Infographic coverage: 0% → 100% Telegram-постів з PNG
• Threads engagement: baseline (TBD після 7 днів) → +20% reply-rate за 30 днів

Залежності і блокери

• Залежить від: Threads access token (валідний у passepartout), Gemini API quota, PIL+DejaVuSans на VPS
• Блокери: Threads reply permission (відомий, тікет до Meta), Gemini timeout на великих batch'ах

Відкриті питання

1. Partial-success policy для seen_ids: позначати seen після Telegram-успіху (Threads/infographic можуть fail) чи лише після all-success?
2. Час публікації Threads — синхронно з Telegram (5/11/17 UTC) чи зміщено (+30 хв для cross-traffic)?
3. Чи додавати лінк на Telegram у фінальний Threads-reply, чи лишати link-on-source-журнал?
4. Кому надсилати daily-digest з метриками (Сергій+Настя у DM bot, чи окремий канал)?

Sign-off

• [ ] Сергій schválив
• [ ] Дата approval: 2026-05-11
• [ ] Перехід на наступну фазу: P (Pseudocode)

🤖 PM Changelog

• 2026-05-11: повне переписання з bootstrap-template на основі реальної pipeline та нового scope (Threads + infographic)