diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01ddfe4..d062421 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,7 @@ Need a stat sources file for an industry not covered (e.g., aerospace, mining, f ### 2-4 hours — Add a new report block -The block library has 103 blocks but specific use cases might need more. +The block library has 105 blocks but specific use cases might need more. **Example:** You want a `decision-tree` block in `compare.md`. diff --git a/QUICKSTART.md b/QUICKSTART.md index 2108419..1ff2597 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -47,6 +47,6 @@ can audit. ## Next steps - Full methodology: [`SKILL.md`](SKILL.md) — the 9-phase workflow. -- The catalog: [`references/`](references/) — 103 report +- The catalog: [`references/`](references/) — 105 report blocks, 6 genres. - Want to add sources or APIs? [`CONTRIBUTING.md`](CONTRIBUTING.md). diff --git a/README.md b/README.md index cc728ce..239daa4 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ The skill runs **9 phases** in order: | **3** | **Plan** | opus / medium | | **3.5** | **Capability Discovery** | sonnet / low | | **4** | **Search** | sonnet / medium | -| **5** | **Scoring + triangulation** | sonnet / medium | +| **5** | **Claims-ledger + triangulation** | haiku / low | | **6** | **Synthesis + multi-angle red team** | opus / high | | **6.5** | **Verify** | haiku / low | | **7** | **Refresh targets** | sonnet / medium | @@ -158,7 +158,7 @@ Every phase is **transparent**: you see what's happening, you confirm key decisi -### 103 Report Blocks +### 105 Report Blocks 10 categories: **FRAME** · **EXPLAIN** · **COMPARE** · **MAP** · **VALIDATE** · **ANALYZE** · **CLOSE** · **PEOPLE** · **NUMBERS** · **CONTEXT** @@ -391,7 +391,7 @@ It's **structured methodology + curated catalog + reusable templates + automatio - The 9-phase workflow forces discipline - 460+ stat sources catalog is curated knowledge -- 103 reusable blocks compose any report shape +- 105 reusable blocks compose any report shape - Weekly auto-validation keeps the catalog alive - 25+ upstream awesome-lists give infinite discovery layer @@ -417,7 +417,7 @@ The methodology is portable. ~70% of content is LLM-agnostic markdown templates. | `SKILL.md` frontmatter | ✓ | — | | Sub-agent `Explore` type | ✓ | — | | 9-phase workflow | — | ✓ | -| 103 report blocks | — | ✓ | +| 105 report blocks | — | ✓ | | 29 search channels | — | ✓ | | 460+ stat sources | — | ✓ | @@ -446,9 +446,9 @@ The methodology is portable. ~70% of content is LLM-agnostic markdown templates. ### Что внутри -- **9 фаз workflow**: Reframing → Genre & block selection → Plan → Capability Discovery → Поиск → Скоринг + триангуляция → Синтез + multi-angle red team → Verify → Refresh targets +- **9 фаз workflow**: Reframing → Genre & block selection → Plan → Capability Discovery → Поиск → Claims-ledger + триангуляция → Синтез + multi-angle red team → Verify → Refresh targets - **6 жанров отчёта**: qa / explainer / decision / landscape / validation / custom -- **103 блоков** в 10 категориях — переиспользуемые секции с шаблонами и анти-паттернами +- **105 блоков** в 10 категориях — переиспользуемые секции с шаблонами и анти-паттернами - **29 каналов поиска** с paywall fallback протоколом (включая api-direct) - **460+ статистических источников** в 14 cross-industry + 19 отраслевых категориях - **39+ API endpoints** для programmatic доступа (free no-auth приоритетны) diff --git a/SKILL.md b/SKILL.md index 8cd9748..c77fc12 100644 --- a/SKILL.md +++ b/SKILL.md @@ -112,8 +112,8 @@ Estimated ~$2 (vs ~$8 если бы всё на Opus). Скажи если ну 2. **Genre & block selection** [`sonnet`/medium] — определить жанр отчёта (qa/explainer/decision/landscape/validation/custom) и набор блоков. Подтвердить пользователю одной строкой. См. `references/genres.md` и `references/blocks/INDEX.md`. 3. **Plan** [`opus`/medium] — записать `plan.md` (5 секций: HEADER → SCOPE → STRUCTURE → EXECUTION → TRACKING). Включает: user context, time-box, acceptance criteria, discovered existing, glossary, жанр + blocks + rationale, гипотезы, risk register, subtopic↔blocks mapping, information sourcing strategy (каналы + stat-источники + API endpoints), opposition queries, stop-criteria, notes для tracking. См. `workflow.md` → Фаза 3 для полного шаблона. 3.5. **Capability Discovery** [`sonnet`/low] (опциональная для shallow, рекомендуется для medium, обязательна для deep) — audit env vars для API ключей, map подтемы → доступные APIs, fallback на upstream awesome-lists для unknown gaps, сводный отчёт пользователю. См. `references/capability_discovery.md`. -4. **Поиск** [main `sonnet`/medium; sub-agents per-task: `haiku` для web/api, `sonnet` для academic/long-source, `opus` для heavy reasoning subtask] — 4 шага: (4.0) **Source Dispatch** — прогнать каждый подвопрос через `source_dispatch.md` matrix, заполнить plan.md секцию 12 с per-subquestion primary/secondary/fallback каналами. (4.1) Launch — для medium/deep: суб-агенты `subagent_type=Explore` в параллель с `model:` параметром из `model_routing.md`, для shallow: главный поток сам. (4.2) Fetch & dedup. (4.3) Save в `sources/NN_slug.md`. Loop: после каждого раунда оркестратор может потратить bounded deviation — включая trajectory-чек промежуточных claims (не плодить поиск на неподтверждённом тезисе) и динамическую ревизию outline (ScaffoldAgent). См. `references/source_dispatch.md`, `references/subagents_v2.md`, `references/workflow.md` → Фаза 4. -5. **Скоринг + триангуляция** [scoring `haiku`/low; triangulation `sonnet`/medium] — каждый источник оценить по 3 осям (Credibility/Recency/Bias). Каждый тезис в выводах — ≥3 независимых источника разного типа. См. `references/source_scoring.md`. +4. **Поиск** [main `sonnet`/medium; sub-agents per-task: `haiku` для web/api, `sonnet` для academic/long-source, `opus` для heavy reasoning subtask] — 4 шага: (4.0) **Source Dispatch** — прогнать каждый подвопрос через `source_dispatch.md` matrix, заполнить plan.md секцию 12. (4.1) Launch — для medium/deep: суб-агенты `subagent_type=general-purpose` (нужен Write) в параллель, каждому свой диапазон номеров источников (`s01-s09`, `s10-s19`, ...); для shallow — главный поток сам. (4.2) Fetch & dedup. (4.3) Save в `sources/NN_slug.md` — пишет сам агент, в главный поток возвращаются только index-строки. Loop: bounded deviation между раундами (trajectory-чек claims, ревизия outline). См. `references/source_dispatch.md`, `references/subagents_v2.md`, `references/workflow.md` → Фаза 4. +5. **Claims-ledger + триангуляция** [`haiku`/low] — из index-строк собирается `claims.csv` (claim_id, sources, status, confidence, primary_source). Механическая триангуляция: ≥3 источника И ≥2 типа → `triangulated`; primary-first — confidence не выше `medium` без primary-источника. Loop: gap-волна на строки не-triangulated, максимум 2 круга, иначе `data-insufficient`. См. `references/source_scoring.md` и `references/workflow.md` → Фаза 5. 6. **Синтез + multi-angle red team** [red-team суб-агенты `opus`/high **обязательно** для deep, `sonnet`/high для medium; synthesis `sonnet`/high] — собрать `_.md` из блоков, затем: draft → claim ledger → N параллельных враждебных ролей (Skeptic / Contrarian / Gap-hunter) как `general-purpose` суб-агенты → триаж по severity → ОДИН раунд ремедиации HIGH (точечный до-поиск или caveat) → финал. Finder ≠ fixer. Гейт: shallow=R1 инлайн, medium=R1+R2, deep=R1+R2+R3 обязательно. См. `references/adversarial_pass.md` и `references/blocks/`. 6.5. **Verify** [`haiku`/low] (medium/deep — обязательно) — runtime-проверка цитат по двум осям: (1) **liveness** — ссылка жива (`check_citations.py`); (2) **faithfulness** — источник реально подтверждает тезис (entailment claim ⊨ цитата из `sources/NN.md`). Битые/неподтверждающие источники чинятся (re-search), смягчаются (overclaim → слабее) или тезис уходит в Open Questions. Отчёт получает verification-header и не «готов» без него. Per-source verification — defensible-фича против закрытых DR-продуктов. См. `references/runtime_verification.md`. 7. **Refresh targets** [`sonnet`/medium] (medium/deep — обязательно) — извлечь entities/numbers/hypotheses/topic-markers из финального отчёта в `refresh_targets.md`. Это точка входа для будущих `update ` — без неё каждый update тратит время на re-discovery «что отслеживать». См. блок Z11 в `references/blocks/close.md` и `references/refresh_protocol.md`. @@ -145,6 +145,7 @@ Estimated ~$2 (vs ~$8 если бы всё на Opus). Скажи если ну / ├── plan.md # Фаза 3 — план + changelog (секция 16) + notes (секция 15) ├── sources.csv # индекс всех источников с оценками +├── claims.csv # Фаза 5 — claim-ledger (claim/sources/status/confidence) ├── sources/ # один файл = один источник (с метаданными + цитаты) │ ├── 01_.md │ ├── 02_.md @@ -171,6 +172,7 @@ Estimated ~$2 (vs ~$8 если бы всё на Opus). Скажи если ну **Шаблоны:** - `sources/NN.md` — см. `references/source_scoring.md` +- `claims.csv` — claim-ledger, см. `references/source_scoring.md` (раздел «Claims-ledger») - `_.md` — собирается из блоков, см. `references/genres.md` (пресеты) и `references/blocks/` (шаблоны блоков) - `findings/FN.md` — атомарный тезис, см. `references/blocks/close.md` (блок Z6) @@ -197,7 +199,8 @@ Estimated ~$2 (vs ~$8 если бы всё на Opus). Скажи если ну - Не обходить ограничения WebFetch через bash/curl. - Не использовать источники с total < 8 как основу для выводов. - Не пропускать multi-angle red team в medium/deep. -- Не использовать `subagent_type=general-purpose` если хватает `Explore` (Explore быстрее и read-only). Исключение — Фаза 6 red team: роли судят, а не ищут → `general-purpose`. +- Для fetch+save (Фаза 4.1) и red team (Фаза 6) — `general-purpose` с явным диапазоном номеров, не `Explore` (read-only, только для разведки). +- Не пропускать gap-волну (нетриангулированные строки `claims.csv`, max 2 круга) и не давать confidence выше `medium` без primary-источника. - Не оставлять «висящие» утверждения без ссылки на конкретный `sources/NN.md`. - Не запускать суб-агентов последовательно — только параллельно в одном сообщении. - Не сжимать sources/ в один файл — теряется поиск и переиспользование между ресёрчами. @@ -219,7 +222,7 @@ URL-friendly: латиница, цифры, дефисы. Пример: - `references/workflow.md` — детали 9 фаз (включая опц. 3.5) (читать в начале medium/deep). - `references/question_reframing.md` — шаблоны Фазы 1. - `references/genres.md` — пресеты блоков 6 жанров + эвристика выбора (Фаза 2) + каналы по жанрам. -- `references/blocks/INDEX.md` — индекс 103 блоков по 10 категориям (после выбора жанра). +- `references/blocks/INDEX.md` — индекс 105 блоков по 10 категориям (после выбора жанра). - `references/channels.md` — 29 каналов поиска (включая api-direct) с query patterns, paywall fallbacks (Фаза 3-4). - `references/stat_sources/INDEX.md` — навигационная карта 33 категорий статистических источников (Фаза 3-4). - `references/api_sources/INDEX.md` — каталог 39+ API endpoints (10 категорий) для programmatic доступа (Фаза 3-4). @@ -230,19 +233,19 @@ URL-friendly: латиница, цифры, дефисы. Пример: - `references/refresh_protocol.md` — **протокол update**: 4 категории дельты (new entrants, entity diff, numbers refresh, adversarial trigger), шаблон `diffs/_delta.md`. Используется в режиме `update `. Дополняется блоком Z11 `refresh-targets` из `blocks/close.md`. **Категорийные файлы (только нужные для выбранного жанра/blocks):** -- `references/blocks/frame.md` — F1-F8: TL;DR, scope, claim, metadata. +- `references/blocks/frame.md` — F1-F10: TL;DR, scope, background, claim, metadata, verification header. - `references/blocks/explain.md` — E1-E14: mental-model, glossary, mechanism. - `references/blocks/compare.md` — C1-C13: matrices, scoring, trade-offs. - `references/blocks/map.md` — M1-M12: profiles, positioning, trends. - `references/blocks/validate.md` — V1-V10: falsification, evidence grades. - `references/blocks/analyze.md` — A1-A13: data tables, SWOT, root cause. -- `references/blocks/close.md` — Z1-Z10: counter-args, open Q, next research. +- `references/blocks/close.md` — Z1-Z12: counter-args, open Q, next research, so-what-for-you. - `references/blocks/people.md` — P1-P7: persona, journey, incentives. - `references/blocks/numbers.md` — N1-N8: metrics, market sizing, forecasts. - `references/blocks/context.md` — X1-X7: regulatory, geo, culture. **По фазам:** -- `references/source_scoring.md` — оценка источников + шаблон `sources/NN.md` с `channel:` и `access:` (Фаза 5). +- `references/source_scoring.md` — оценка источников + шаблон `sources/NN.md` с `channel:` и `access:`; claims-ledger (`claims.csv`) и правило primary-first (Фаза 5). - `references/subagents_v2.md` — паттерн суб-агентов с CHANNELS TO USE (Фаза 4, medium/deep). - `references/adversarial_pass.md` — multi-angle red team: роли, триаж severity, ограниченный цикл ремедиации (Фаза 6, medium/deep). - `references/runtime_verification.md` — runtime-проверка цитат: резолв тезисов к sources/NN.md, verification-header (Фаза 6.5, medium/deep). diff --git a/docs/_config.yml b/docs/_config.yml index 919cbdf..a764e25 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -3,7 +3,7 @@ # or by GitHub Pages for the docs/ folder. title: Deep Research -description: A structured 9-phase meta-research skill for Claude Code. 29 channels, 460+ stat sources, 103 report blocks. +description: A structured 9-phase meta-research skill for Claude Code. 29 channels, 460+ stat sources, 105 report blocks. url: https://socialpranker.github.io baseurl: /claude-deep-research diff --git a/docs/index.html b/docs/index.html index 1f2254b..d87b7f0 100644 --- a/docs/index.html +++ b/docs/index.html @@ -9,7 +9,7 @@ - + @@ -1027,7 +1027,7 @@

Search channels
-
103
+
105
Report blocks
@@ -1159,14 +1159,14 @@

Refresh

§ 03 · catalog

A curated catalog.
Auto-validated weekly.

- 460+ statistical sources, 39+ API endpoints, 29 named channels, 103 report blocks. + 460+ statistical sources, 39+ API endpoints, 29 named channels, 105 report blocks. Weekly cron in GitHub Actions validates endpoints and discovers upstream additions.

/blocks -
103 / 10 categories
+
105 / 10 categories

Report Blocks

Reusable sections with templates, anti-patterns, and composition rules. Each block has a fixed shape — you compose a report by naming the blocks it contains.

@@ -1333,7 +1333,7 @@

Frequently asked.

Is this just prompt engineering?
- It's structured methodology plus a curated catalog plus reusable templates plus automation. The 9-phase workflow forces discipline. 460+ stat sources is curated knowledge. 103 reusable blocks compose any report shape. Weekly auto-validation keeps the catalog alive. 25+ upstream awesome-lists give a discovery layer. Prompts are an implementation detail, not the value. + It's structured methodology plus a curated catalog plus reusable templates plus automation. The 9-phase workflow forces discipline. 460+ stat sources is curated knowledge. 105 reusable blocks compose any report shape. Weekly auto-validation keeps the catalog alive. 25+ upstream awesome-lists give a discovery layer. Prompts are an implementation detail, not the value.
@@ -1377,7 +1377,7 @@

const translations = { en: { 'meta.title': 'Deep Research — Claude Code Skill for Documented Investigation', - 'meta.description': 'A 9-phase meta-research skill for Claude Code. Stop ad-hoc Googling, start documented investigation. 460+ stat sources, 39+ APIs, 103 report blocks, weekly auto-validation.', + 'meta.description': 'A 9-phase meta-research skill for Claude Code. Stop ad-hoc Googling, start documented investigation. 460+ stat sources, 39+ APIs, 105 report blocks, weekly auto-validation.', 'nav.how': 'how it works', 'nav.catalog': 'catalog', @@ -1452,8 +1452,8 @@

'inside.tag': '§ 03 · catalog', 'inside.title': 'A curated catalog.
Auto-validated weekly.', - 'inside.intro': '460+ statistical sources, 39+ API endpoints, 29 named channels, 103 report blocks. Weekly cron in GitHub Actions validates endpoints and discovers upstream additions.', - 'inside.f1.num': '103 / 10 categories', + 'inside.intro': '460+ statistical sources, 39+ API endpoints, 29 named channels, 105 report blocks. Weekly cron in GitHub Actions validates endpoints and discovers upstream additions.', + 'inside.f1.num': '105 / 10 categories', 'inside.f1.title': 'Report Blocks', 'inside.f1.desc': 'Reusable sections with templates, anti-patterns, and composition rules. Each block has a fixed shape — you compose a report by naming the blocks it contains.', 'inside.f1.more': '+71 more', @@ -1506,7 +1506,7 @@

'faq.q4': "What if I don't have CLAUDE.md or a project context?", 'faq.a4': 'The skill detects context in 3 tiers: explicit (CLAUDE.md research_root setting) → autodetect (pyproject.toml, package.json) → fallback (~/deep-research/). No project, no problem.', 'faq.q5': 'Is this just prompt engineering?', - 'faq.a5': "It's structured methodology plus a curated catalog plus reusable templates plus automation. The 9-phase workflow forces discipline. 460+ stat sources is curated knowledge. 103 reusable blocks compose any report shape. Weekly auto-validation keeps the catalog alive. 25+ upstream awesome-lists give a discovery layer. Prompts are an implementation detail, not the value.", + 'faq.a5': "It's structured methodology plus a curated catalog plus reusable templates plus automation. The 9-phase workflow forces discipline. 460+ stat sources is curated knowledge. 105 reusable blocks compose any report shape. Weekly auto-validation keeps the catalog alive. 25+ upstream awesome-lists give a discovery layer. Prompts are an implementation detail, not the value.", 'faq.q6': 'Can I use this commercially?', 'faq.a6': 'Yes — MIT licensed. Use it, modify it, integrate it into products. Attribution appreciated but not required.', @@ -1522,7 +1522,7 @@

}, ru: { 'meta.title': 'Deep Research — навык Claude Code для задокументированного исследования', - 'meta.description': 'Навык meta-research для Claude Code из 9 фаз. Не ад-хок поиск в Google, а исследование с источниками. 460+ статистических источников, 39+ API, 103 блоков отчёта, авто-валидация раз в неделю.', + 'meta.description': 'Навык meta-research для Claude Code из 9 фаз. Не ад-хок поиск в Google, а исследование с источниками. 460+ статистических источников, 39+ API, 105 блоков отчёта, авто-валидация раз в неделю.', 'nav.how': 'как работает', 'nav.catalog': 'каталог', @@ -1597,8 +1597,8 @@

'inside.tag': '§ 03 · каталог', 'inside.title': 'Кураторский каталог.
Авто-валидация раз в неделю.', - 'inside.intro': '460+ статистических источников, 39+ API endpoints, 29 именованных каналов, 103 блоков отчёта. Еженедельный cron в GitHub Actions проверяет endpoints и подхватывает новые из awesome-листов.', - 'inside.f1.num': '103 / 10 категорий', + 'inside.intro': '460+ статистических источников, 39+ API endpoints, 29 именованных каналов, 105 блоков отчёта. Еженедельный cron в GitHub Actions проверяет endpoints и подхватывает новые из awesome-листов.', + 'inside.f1.num': '105 / 10 категорий', 'inside.f1.title': 'Блоки отчёта', 'inside.f1.desc': 'Переиспользуемые секции с шаблонами, анти-паттернами и правилами композиции. У каждого блока — фиксированная форма; отчёт собирается перечислением блоков.', 'inside.f1.more': '+71 ещё', @@ -1651,7 +1651,7 @@

'faq.q4': 'А если нет CLAUDE.md или контекста проекта?', 'faq.a4': 'Скилл определяет контекст по 3 уровням: явный (CLAUDE.md с research_root) → автодетект (pyproject.toml, package.json) → fallback (~/deep-research/). Нет проекта — не проблема.', 'faq.q5': 'Это просто prompt engineering?', - 'faq.a5': 'Это структурированная методология плюс кураторский каталог плюс переиспользуемые шаблоны плюс автоматизация. Workflow из 9 фаз дисциплинирует. 460+ стат-источников — это куратный домен. 103 блоков складываются в любую форму отчёта. Авто-валидация раз в неделю держит каталог живым. 25+ awesome-листов дают слой discovery. Промпты — это implementation detail, не ценность.', + 'faq.a5': 'Это структурированная методология плюс кураторский каталог плюс переиспользуемые шаблоны плюс автоматизация. Workflow из 9 фаз дисциплинирует. 460+ стат-источников — это куратный домен. 105 блоков складываются в любую форму отчёта. Авто-валидация раз в неделю держит каталог живым. 25+ awesome-листов дают слой discovery. Промпты — это implementation detail, не ценность.', 'faq.q6': 'Можно использовать коммерчески?', 'faq.a6': 'Да — лицензия MIT. Используй, модифицируй, встраивай в продукты. Атрибуция приветствуется, но не обязательна.', diff --git a/phases.yaml b/phases.yaml index b2ee15e..2dfe73a 100644 --- a/phases.yaml +++ b/phases.yaml @@ -43,12 +43,17 @@ phases: effort: medium depth_gate: shallow loop: "true" + # Phase 5 includes a gap-wave LOOP after the first claims.csv pass: rows + # with status != triangulated get one targeted haiku/low sub-agent each, + # max 2 rounds, else marked data-insufficient. Same convention as Phase 4 — + # no new phase id for the loop, see references/workflow.md "Фаза 5". - id: "5" - name_ru: "Скоринг + триангуляция" - name_en: "Scoring + triangulation" - model: sonnet - effort: medium + name_ru: "Claims-ledger + триангуляция" + name_en: "Claims-ledger + triangulation" + model: haiku + effort: low depth_gate: shallow + loop: "true" - id: "6" name_ru: "Синтез + multi-angle red team" name_en: "Synthesis + multi-angle red team" diff --git a/references/adversarial_pass.md b/references/adversarial_pass.md index 364d520..15c14be 100644 --- a/references/adversarial_pass.md +++ b/references/adversarial_pass.md @@ -10,7 +10,8 @@ Все роли — одна семья моделей, общие слепые зоны остаются. - ЛОВИТ: overclaim (источник не доказывает тезис), тезисы с <3 независимыми источниками, дыры покрытия, проигнорированную контр-гипотезу, selection bias, - подгонку под пользователя. + подгонку под пользователя, числа без якоря сравнения, выводы без проекции на + кейс пользователя (Z12), рекомендации без trade-off/kill-criteria. - НЕ ЛОВИТ: общие фактические галлюцинации (коррелированы). Их держит триангуляция (Фаза 5) и опц. кросс-вендорная 6.5. → red team ДОПОЛНЯЕТ триангуляцию, не заменяет. @@ -51,7 +52,10 @@ R2 — Адвокат противоположной гипотезы: R3 — Охотник за пропусками + анти-сикофантия: «Что отсутствует, но релевантно решению? Проверь: (а) подгонку под ожидания пользователя; (б) selection bias (все источники одного типа/лагеря); - (в) непокрытые стейкхолдеры/сценарии/издержки/риски.» + (в) непокрытые стейкхолдеры/сценарии/издержки/риски; (г) есть ли числа без + якоря сравнения (голое "$4.5B" без базы), выводы без проекции на кейс + пользователя (блок Z12 so-what-for-you пустой или формальный), рекомендации + без trade-off/kill-criteria.» ## 3. Триаж severity (структурные вердикты, НЕ скоры 1–5) @@ -64,6 +68,7 @@ R3 — Охотник за пропусками + анти-сикофантия: ## 4. Привязка к остальному скиллу - stop-criteria: опозиционные запросы R2 = выполнение «≥1 целевой поиск оппозиции». -- blocks/close.md: дефекты → counter-arguments + Open Questions (HIGH без закрытия → Open Questions «данных мало»). +- blocks/close.md: дефекты → counter-arguments + Open Questions (HIGH без закрытия → Open Questions «данных мало»); числа-без-якоря/пустой-Z12/рекомендации-без-trade-off от R3(г) → правки блоков F9/Z12 или соответствующих N/A-блоков синтеза, не отдельная секция. - plan.md risk register: неустранённые HIGH. - refresh_targets.md: контр-гипотезы R2 → hypotheses-to-track. +- claims.csv: HIGH-дефекты про overclaim/<3 источника пересекаются с status ≠ triangulated — red team может подсветить строку, которую gap-волна (Фаза 5) не закрыла. diff --git a/references/blocks/INDEX.md b/references/blocks/INDEX.md index c2cb0ba..9c9dd19 100644 --- a/references/blocks/INDEX.md +++ b/references/blocks/INDEX.md @@ -1,6 +1,6 @@ # Block Library — INDEX -103 блоков в 10 категориях. Композируемые секции для финального отчёта. +105 блоков в 10 категориях. Композируемые секции для финального отчёта. ## Как использовать @@ -13,18 +13,18 @@ | Cat | Файл | Блоки | Назначение | |---|---|---|---| -| FRAME | [frame.md](frame.md) | F1-F8 | Рамка отчёта: TL;DR, scope, claim, metadata | +| FRAME | [frame.md](frame.md) | F1-F10 | Рамка отчёта: TL;DR, scope, background, claim, metadata | | EXPLAIN | [explain.md](explain.md) | E1-E14 | Объяснение устройства: mental model, glossary, mechanism | | COMPARE | [compare.md](compare.md) | C1-C13 | Сравнение и выбор: matrices, scoring, trade-offs | | MAP | [map.md](map.md) | M1-M12 | Картография: profiles, positioning, trends | | VALIDATE | [validate.md](validate.md) | V1-V10 | Проверка истинности: falsification, evidence grades | | ANALYZE | [analyze.md](analyze.md) | A1-A13 | Структурированный анализ: SWOT, timeline, root cause | -| CLOSE | [close.md](close.md) | Z1-Z11 | Закрытие: counter-args, open Q, next research | +| CLOSE | [close.md](close.md) | Z1-Z12 | Закрытие: counter-args, open Q, next research | | PEOPLE | [people.md](people.md) | P1-P7 | Люди, команды, поведение: persona, journey, incentives | | NUMBERS | [numbers.md](numbers.md) | N1-N8 | Количественные: метрики, market sizing, forecasts | | CONTEXT | [context.md](context.md) | X1-X7 | Внешний контекст: регуляторика, гео, культура | -## Полная таблица всех 103 блоков +## Полная таблица всех 105 блоков ### FRAME @@ -38,6 +38,8 @@ | F6 | `key-finding-callout` | Главный single insight выделенный | Длинные отчёты | | F7 | `executive-summary` | 1-страничный TL;DR для стейкхолдеров | Decision/landscape для не-технических | | F8 | `glossary-link` | Ссылка на внешний/общий глоссарий | Если есть проектный glossary | +| F9 | `background` | Почему вопрос стоит так — предыстория, причины, 5-10 строк | Medium/deep, все жанры (дефолт) | +| F10 | `verification-header` | Citation integrity (liveness + faithfulness) | Medium/deep, после Фазы 6.5 verify | ### EXPLAIN @@ -141,6 +143,7 @@ | Z9 | `glossary-final` | Финальный глоссарий из отчёта | Длинные с обильной терминологией | | Z10 | `update-triggers` | Что должно произойти для update | Все ресёрчи (life cycle) | | Z11 | `refresh-targets` (отдельный файл) | Что конкретно проверять при update — entities, numbers, hypotheses | Medium/deep — обязательно | +| Z12 | `so-what-for-you` | Проекция выводов на кейс пользователя: действие + trade-off + kill-criteria | Medium/deep — обязательно | ### PEOPLE @@ -181,7 +184,7 @@ ## Progressive loading discipline -При 103 блоках критично не загружать всё в контекст. +При 105 блоках критично не загружать всё в контекст. ``` Главный поток: diff --git a/references/blocks/close.md b/references/blocks/close.md index bd0bb46..df1a4f8 100644 --- a/references/blocks/close.md +++ b/references/blocks/close.md @@ -515,3 +515,39 @@ If specific sources are critical to the report's conclusions, they get extra re- - ❌ Перечислять «все возможные источники» — это refresh_targets, а не bibliographic database. Только critical-path - ❌ Без update_cadence — пользователь не поймёт когда возвращаться - ❌ Без сохранённых hash/snapshot для entity pages — fingerprinting не работает + +--- + +## Z12 — `so-what-for-you` + +**Когда:** Medium/deep, обязательно. Проекция ключевых выводов отчёта на конкретный кейс пользователя — а не абстрактное «вот что мы узнали про мир». + +**Вход:** `plan.md` секция 0 (User context — кто спрашивает, зачем, как будет использовать отчёт) + `claims.csv` (ключевые тезисы с их confidence). + +**Что внутри:** Для каждого ключевого вывода — что это значит именно для ситуации пользователя, конкретное действие, trade-off этого действия, и kill-criteria (что должно произойти, чтобы рекомендация перестала быть верной). + +**Антипаттерн:** Повторение TL;DR другими словами. Z12 должен добавлять то, чего нет в TL;DR — персонализацию под конкретный кейс из `plan.md` секции 0, а не пересказ фактов. + +**Композиция:** После `map-of-sources` [Z5] / `confidence-summary` [Z7], **перед** `actionable-next-steps` [Z4] — сначала «что это значит для тебя», потом «что конкретно делать». + +**Шаблон:** + +```markdown +## So what for you + +Контекст использования (из plan.md §0): <кто спрашивает, зачем, как использует> + +### Вывод 1: <ключевой тезис из claims.csv, confidence: high/medium/low> +**Что это значит для твоей ситуации:** <конкретная проекция, не абстракция> +**Рекомендуемое действие:** <что делать с учётом этого> +**Trade-off:** <что теряешь, выбирая это действие> +**Kill-criteria:** <что должно произойти, чтобы эта рекомендация перестала быть верной> + +### Вывод 2: <тезис, confidence> +**Что это значит:** ... +**Действие:** ... +**Trade-off:** ... +**Kill-criteria:** ... + +### Вывод 3: ... +``` diff --git a/references/blocks/frame.md b/references/blocks/frame.md index fc5a012..78ede07 100644 --- a/references/blocks/frame.md +++ b/references/blocks/frame.md @@ -205,3 +205,28 @@ - **<Термин 1>** — <определение> - **<Термин 2>** — <определение> ``` + +--- + +## F9 — `background` + +**Когда:** Дефолт для medium/deep во всех жанрах. Отвечает на «почему вопрос вообще стоит так, как стоит» — до того как начинаем разбирать содержание. + +**Что внутри:** Предыстория и причины — что было до этого вопроса, откуда он взялся, какие события/решения привели к тому, что он актуален сейчас. 5-10 строк, не больше — это контекст, не отдельный ресёрч в ресёрче. + +**Антипаттерн:** Пересказ Википедии о теме целиком. Background должен объяснять именно ПОЧЕМУ вопрос стоит так, не давать общую историю предмета. + +**Композиция:** После `scope` [F3] (если scope есть) или сразу после `tldr` [F1]. До основного содержимого отчёта. + +**Шаблон:** + +```markdown +## Background + +<5-10 строк: что предшествовало этому вопросу — событие, тренд, решение, изменение +условий — из-за которого вопрос стал релевантным именно сейчас. Явно называй +источники предпосылки, если они есть: [s03].> + +**Почему это важно для ответа:** <короткая связка — как эта предыстория влияет на +то, как нужно читать остальной отчёт> +``` diff --git a/references/genres.md b/references/genres.md index 6e624ef..c996703 100644 --- a/references/genres.md +++ b/references/genres.md @@ -56,25 +56,28 @@ **Когда:** Серия связанных вопросов, meta-research, тема без явного жанра. -**Required blocks:** `tldr`, `qa-list`, `map-of-sources`, `metadata` +**Required blocks:** `tldr`, `qa-list`, `map-of-sources`, `metadata`. Для medium/deep — обязательно ещё: `background` [F9], `so-what-for-you` [Z12], `actionable-next-steps` [Z4], `confidence-summary` [Z7]. **Recommended order:** ``` 1. tldr [F1] -2. decision-context [F2] (если есть decision) -3. qa-list [A3] ← главная секция -4. hypotheses-outcome [A4] (если в plan были hypotheses) -5. counter-arguments [Z1] (medium/deep) -6. open-questions [Z2] -7. next-research [Z3] -8. map-of-sources [Z5] -9. findings-index [Z6] (если есть) -10. metadata [F5] +2. background [F9] +3. decision-context [F2] (если есть decision) +4. qa-list [A3] ← главная секция +5. hypotheses-outcome [A4] (если в plan были hypotheses) +6. counter-arguments [Z1] (medium/deep) +7. open-questions [Z2] +8. next-research [Z3] +9. confidence-summary [Z7] +10. so-what-for-you [Z12] (перед Z4) +11. actionable-next-steps [Z4] +12. map-of-sources [Z5] +13. findings-index [Z6] (если есть) +14. metadata [F5] ``` **Опциональные additions:** - `key-finding-callout` [F6] если есть один доминирующий insight -- `confidence-summary` [Z7] для длинных отчётов --- @@ -82,26 +85,30 @@ **Когда:** Понять устройство темы, mental model, не decision. -**Required blocks:** `tldr`, `mental-model`, `stepwise`, `map-of-sources`, `metadata` +**Required blocks:** `tldr`, `mental-model`, `stepwise`, `map-of-sources`, `metadata`. Для medium/deep — обязательно ещё: `background` [F9], `so-what-for-you` [Z12], `actionable-next-steps` [Z4], `confidence-summary` [Z7]. **Recommended order:** ``` 1. tldr [F1] -2. prerequisites [E8] (если нужно background) -3. glossary-mini [E2] ← термины перед схемой -4. mental-model [E1] ← схема устройства -5. stepwise [E4] ← как работает -6. variants [E5] (если есть варианты реализации) -7. worked-example [E6] (для education-style) -8. common-confusions [E7] -9. failure-modes [E10] (для технических тем) -10. edge-cases [E11] (опционально) -11. design-rationale [E12] (для architecture explainer) -12. counter-arguments [Z1] -13. open-questions [Z2] -14. next-research [Z3] -15. map-of-sources [Z5] -16. metadata [F5] +2. background [F9] +3. prerequisites [E8] (если нужно читателю) +4. glossary-mini [E2] ← термины перед схемой +5. mental-model [E1] ← схема устройства +6. stepwise [E4] ← как работает +7. variants [E5] (если есть варианты реализации) +8. worked-example [E6] (для education-style) +9. common-confusions [E7] +10. failure-modes [E10] (для технических тем) +11. edge-cases [E11] (опционально) +12. design-rationale [E12] (для architecture explainer) +13. counter-arguments [Z1] +14. open-questions [Z2] +15. next-research [Z3] +16. confidence-summary [Z7] +17. so-what-for-you [Z12] (перед Z4) +18. actionable-next-steps [Z4] +19. map-of-sources [Z5] +20. metadata [F5] ``` **Подмножество для глубокого technical:** @@ -118,34 +125,37 @@ **Когда:** Сравнение опций для принятия решения. С явной рекомендацией. -**Required blocks:** `tldr`, `decision-context`, `options-matrix`, `recommendation-conditional`, `map-of-sources`, `metadata` +**Required blocks:** `tldr`, `decision-context`, `options-matrix`, `recommendation-conditional`, `map-of-sources`, `metadata`. Для medium/deep — обязательно ещё: `background` [F9], `so-what-for-you` [Z12], `confidence-summary` [Z7]. **Recommended order:** ``` 1. tldr [F1] -2. executive-summary [F7] (опционально, для стейкхолдеров) -3. decision-context [F2] ← рамка решения -4. options-matrix [C1] -5. weighted-score [C2] (если критерии неравнозначны) -6. feature-matrix [C10] (для product decisions) -7. pros-cons-each [C9] (alternative to matrix для quick) -8. best-fit-when [C3] -9. trade-offs [C5] -10. reversibility-stakes [C4] -11. cost-benefit [C8] (для финансовых) -12. risk-register [A6] (для рискованных) -13. pre-mortem [C7] (high-stakes) -14. migration-path [C11] (если обратимо) -15. decision-tree [C12] (для сложных мультиусловных) -16. kill-criteria [C13] -17. counter-arguments [Z1] -18. recommendation-conditional [C6] ← финальная рекомендация -19. actionable-next-steps [Z4] -20. assumptions-log [Z8] -21. open-questions [Z2] -22. next-research [Z3] -23. map-of-sources [Z5] -24. metadata [F5] +2. background [F9] +3. executive-summary [F7] (опционально, для стейкхолдеров) +4. decision-context [F2] ← рамка решения +5. options-matrix [C1] +6. weighted-score [C2] (если критерии неравнозначны) +7. feature-matrix [C10] (для product decisions) +8. pros-cons-each [C9] (alternative to matrix для quick) +9. best-fit-when [C3] +10. trade-offs [C5] +11. reversibility-stakes [C4] +12. cost-benefit [C8] (для финансовых) +13. risk-register [A6] (для рискованных) +14. pre-mortem [C7] (high-stakes) +15. migration-path [C11] (если обратимо) +16. decision-tree [C12] (для сложных мультиусловных) +17. kill-criteria [C13] +18. counter-arguments [Z1] +19. recommendation-conditional [C6] ← финальная рекомендация +20. confidence-summary [Z7] +21. so-what-for-you [Z12] (перед Z4) +22. actionable-next-steps [Z4] +23. assumptions-log [Z8] +24. open-questions [Z2] +25. next-research [Z3] +26. map-of-sources [Z5] +27. metadata [F5] ``` **Подмножества:** @@ -158,30 +168,34 @@ **Когда:** Игроки/решения в области, без приоритета выбора. -**Required blocks:** `tldr`, `scope`, `categories`, `profile-card`, `map-of-sources`, `metadata` +**Required blocks:** `tldr`, `scope`, `categories`, `profile-card`, `map-of-sources`, `metadata`. Для medium/deep — обязательно ещё: `background` [F9], `so-what-for-you` [Z12], `actionable-next-steps` [Z4], `confidence-summary` [Z7]. **Recommended order:** ``` 1. tldr [F1] -2. scope [F3] ← границы карты -3. categories [M1] ← деление области -4. profile-card × N [M2] ← карточки игроков по категориям -5. key-people [P3] (для глубоких landscape) -6. positioning-map [M3] -7. value-chain [M8] (industry analysis) -8. network-graph [M9] (relationships) -9. funding-tree [M10] (startup ecosystem) -10. geographic-distribution [M11] (geo-distributed) -11. lifecycle-stage [M12] -12. trends [M4] -13. white-spaces [M5] (для product strategy) -14. ecosystem [X7] (broader context) -15. counter-arguments [Z1] -16. open-questions [Z2] -17. next-research [Z3] -18. update-triggers [Z10] ← landscape устаревает быстро -19. map-of-sources [Z5] -20. metadata [F5] +2. background [F9] +3. scope [F3] ← границы карты +4. categories [M1] ← деление области +5. profile-card × N [M2] ← карточки игроков по категориям +6. key-people [P3] (для глубоких landscape) +7. positioning-map [M3] +8. value-chain [M8] (industry analysis) +9. network-graph [M9] (relationships) +10. funding-tree [M10] (startup ecosystem) +11. geographic-distribution [M11] (geo-distributed) +12. lifecycle-stage [M12] +13. trends [M4] +14. white-spaces [M5] (для product strategy) +15. ecosystem [X7] (broader context) +16. counter-arguments [Z1] +17. open-questions [Z2] +18. next-research [Z3] +19. update-triggers [Z10] ← landscape устаревает быстро +20. confidence-summary [Z7] +21. so-what-for-you [Z12] (перед Z4) +22. actionable-next-steps [Z4] +23. map-of-sources [Z5] +24. metadata [F5] ``` **Подмножества:** @@ -194,32 +208,35 @@ **Когда:** Проверка claim. С verdict. -**Required blocks:** `tldr`, `claim-precise`, `falsification-criteria`, `evidence-graded`, `verdict-conditional`, `map-of-sources`, `metadata` +**Required blocks:** `tldr`, `claim-precise`, `falsification-criteria`, `evidence-graded`, `verdict-conditional`, `map-of-sources`, `metadata`. Для medium/deep — обязательно ещё: `background` [F9], `so-what-for-you` [Z12], `confidence-summary` [Z7]. **Recommended order:** ``` 1. tldr [F1] -2. claim-precise [F4] ← точная формулировка -3. scope [F3] ← где применимо -4. base-rates [V4] (для probabilistic claims) -5. falsification-criteria [V1] ← ДО evidence -6. evidence-graded [V2] ← FOR/AGAINST -7. conflicting-evidence [V3] (если есть) -8. replication-status [V7] (для научных claims) -9. sample-size-analysis [V8] (для quantitative) -10. methodology-critique [V9] (deep) -11. expert-opinion [P7] (если expert-driven) -12. bayesian-update [V10] (для probabilistic) -13. verdict-conditional [V5] ← главный verdict -14. what-would-change-verdict [V6] -15. common-confusions [E7] (часто claim путают с X) -16. counter-arguments [Z1] -17. actionable-next-steps [Z4] (что делать с этим verdict) -18. assumptions-log [Z8] -19. open-questions [Z2] -20. next-research [Z3] -21. map-of-sources [Z5] -22. metadata [F5] +2. background [F9] +3. claim-precise [F4] ← точная формулировка +4. scope [F3] ← где применимо +5. base-rates [V4] (для probabilistic claims) +6. falsification-criteria [V1] ← ДО evidence +7. evidence-graded [V2] ← FOR/AGAINST +8. conflicting-evidence [V3] (если есть) +9. replication-status [V7] (для научных claims) +10. sample-size-analysis [V8] (для quantitative) +11. methodology-critique [V9] (deep) +12. expert-opinion [P7] (если expert-driven) +13. bayesian-update [V10] (для probabilistic) +14. verdict-conditional [V5] ← главный verdict +15. what-would-change-verdict [V6] +16. common-confusions [E7] (часто claim путают с X) +17. counter-arguments [Z1] +18. confidence-summary [Z7] +19. so-what-for-you [Z12] (перед Z4) +20. actionable-next-steps [Z4] (что делать с этим verdict) +21. assumptions-log [Z8] +22. open-questions [Z2] +23. next-research [Z3] +24. map-of-sources [Z5] +25. metadata [F5] ``` **Подмножества:** @@ -232,7 +249,7 @@ **Когда:** Вопрос не подходит ни под один стандартный жанр. Гибридные вопросы. Специфические аналитические задачи. -**Required (всегда):** `tldr`, `map-of-sources`, `metadata` +**Required (всегда):** `tldr`, `map-of-sources`, `metadata`. Для medium/deep — обязательно ещё: `background` [F9], `so-what-for-you` [Z12], `actionable-next-steps` [Z4], `confidence-summary` [Z7]. **Эвристика подбора блоков:** @@ -266,13 +283,17 @@ **Базовая обвязка для custom:** ``` 1. tldr [F1] -2. scope [F3] (если границы важны) -3. <выбранные блоки по эвристике> -4. counter-arguments [Z1] -5. open-questions [Z2] -6. next-research [Z3] -7. map-of-sources [Z5] -8. metadata [F5] +2. background [F9] +3. scope [F3] (если границы важны) +4. <выбранные блоки по эвристике> +5. counter-arguments [Z1] +6. open-questions [Z2] +7. next-research [Z3] +8. confidence-summary [Z7] +9. so-what-for-you [Z12] (перед actionable-next-steps) +10. actionable-next-steps [Z4] +11. map-of-sources [Z5] +12. metadata [F5] ``` **Подтверждение пользователя:** скилл выводит одной строкой: @@ -326,6 +347,7 @@ counter-args, open-q, sources, metadata] - `tldr` [F1] — первый блок (но пишется ПОСЛЕДНИМ) - `map-of-sources` [Z5] — обязательно - `metadata` [F5] — последний (footer) +- Для medium/deep во ВСЕХ жанрах — обязательно: `background` [F9], `so-what-for-you` [Z12], `actionable-next-steps` [Z4], `confidence-summary` [Z7] (см. секции жанров выше). ### Mutually exclusive (не использовать вместе) - `glossary-mini` ИЛИ `glossary-full` ИЛИ `glossary-link` — выбирай ОДИН @@ -335,11 +357,13 @@ counter-args, open-q, sources, metadata] ### Порядок зависимостей - `glossary-*` идёт ПЕРЕД `mental-model` (термины перед схемой) +- `background` [F9] идёт СРАЗУ ПОСЛЕ `tldr`/перед `scope` — контекст «почему вопрос» перед рамкой и содержимым - `scope` ПЕРЕД основными блоками (рамка перед содержимым) - `claim-precise` ПЕРЕД `falsification-criteria` ПЕРЕД `evidence-graded` - `base-rates` ПЕРЕД `evidence-graded` (prior перед update) - `counter-arguments` ПОСЛЕ основного содержимого, ПЕРЕД closing - `recommendation-conditional` ПОСЛЕ всех comparison-блоков +- `so-what-for-you` [Z12] ПОСЛЕ `confidence-summary`/`map-of-sources` секций, но ПЕРЕД `actionable-next-steps` [Z4] — сначала проекция на кейс, потом конкретные действия ### Density rules - Shallow отчёт: 5-9 блоков diff --git a/references/model_routing.md b/references/model_routing.md index 9539897..5be2801 100644 --- a/references/model_routing.md +++ b/references/model_routing.md @@ -13,6 +13,7 @@ 3. **Параллелизм — повод для дешёвой модели.** Если запускаем 5 sub-agents в Phase 4, они должны быть на Haiku/Sonnet, не на Opus. Иначе цена ресёрча умножается на 5. 4. **Финальные deliverables — повод для дорогой модели.** Phase 1 reframing, Phase 6 adversarial, Phase 7 synthesis — это где качество мультиплицируется на весь ресёрч. Не экономить. 5. **Главный поток vs sub-agent.** Главный поток (где живёт пользователь) обычно требует Sonnet+ для диалога. Sub-agents можно сильно дешевле — у них узкая задача с фиксированным output. +6. **Экономика сместилась: Opus всего 5× от Haiku** (см. Cost economics ниже). Не экономь на критических одиночных вызовах (reframing, adversarial) — экономь на fan-out (N параллельных sub-agents в Phase 4 и в gap-волне внутри Phase 5). --- @@ -26,15 +27,17 @@ | **Phase 3** | Plan composition (17 секций) | **Opus** | medium | Архитектурное решение, документирует все будущие выборы | | **Phase 3.5** | Capability discovery — env vars audit, mapping | **Sonnet** | low | Механический проход, простые таблицы | | **Phase 4.0** | Source Dispatch — прогон подвопросов через matrix | **Sonnet** | medium | Lookup в `source_dispatch.md` + запись в plan.md | -| **Phase 4.1** | Launch sub-agents (web search, simple lookups) | **Haiku** | low | Sub-agents с узкой задачей и JSON output. Дёшево × N агентов | +| **Phase 4.1** | Launch sub-agents (web search, simple lookups) | **Haiku** | low | Sub-agents с узкой задачей и JSON output. Дёшево × N агентов. Скорит сам, см. Phase 5 | | **Phase 4.1** | Launch sub-agents (чтение длинных источников, извлечение цитат) | **Sonnet** | low | Когда нужен длинный контекст под цитаты | | **Phase 4.1** | Launch sub-agents (api-direct: curl + jq + parse) | **Haiku** | low | Bash работа + механический парсинг JSON | | **Phase 4.1** | Launch sub-agents (анализ кода в репозитории) | **Sonnet** | medium | Code understanding требует средней модели | | **Phase 4.2** | Fetch + dedup (главный поток) | **Sonnet** | medium | Управляет sub-agents, агрегирует результаты | -| **Phase 4.3** | Save sources to files | **Haiku** | low | Механическая запись по шаблону | -| **Phase 5** | Scoring (credibility/recency/bias по rubric) | **Haiku** | low | Простой паттерн оценки. Sonnet излишен | -| **Phase 5** | Triangulation check (3 источника на claim) | **Sonnet** | medium | Понимание содержания, не только URL | +| **Phase 4.3** | Save sources to files | **Haiku** | low | Пишет сам fetch-агент в свой диапазон номеров, см. `subagents_v2.md` | +| **Phase 4.5** | Gap-волна — точечные агенты на дыры в `claims.csv` (status ≠ triangulated), максимум 2 круга | **Haiku** | low | Узкая задача «найди ещё один источник типа X на claim Y» — не нужна дорогая модель | +| **Phase 5** | Scoring (credibility/recency/bias по rubric) | *(встроено в Phase 4.1, см. выше)* | — | Отдельный проход не запускается — скорит тот агент, который читал источник | +| **Phase 5** | Triangulation check по `claims.csv` (механическая: ≥3 источника И ≥2 типа → triangulated) | **Haiku** | low | Правило механическое — подсчёт источников/типов по строке, не нужна дорогая модель | | **Phase 6** | Multi-angle red team — N враждебных ролей как суб-агенты | **Opus** | high | **Самая дорогая модель здесь обязательна.** Атака на гипотезы (Skeptic/Contrarian/Gap-hunter) требует настоящего рассуждения, не паттерн-матчинга. Medium → sonnet/high | +| **Phase 6.5** | Verify — liveness + faithfulness цитат | **Haiku** | low | Механическая проверка + entailment на коротких парах claim⊨quote | | **Phase 7** | Synthesis — сборка отчёта из блоков | **Sonnet** | high | Длинный контекст всех источников + блоков + плана. Sonnet/high лучше чем Opus/medium здесь | | **Phase 7** | Final report write-up (язык, стиль, чистка) | **Sonnet** | medium | Качественное письмо | @@ -58,32 +61,26 @@ Phase 6 red-team суб-агенты: deep → opus/high; medium → sonnet/high **Default для sub-agent** если не уверен → **Sonnet / low**. Это safe middle ground. +**Скоринг встроен.** Каждый fetch sub-agent сам скорит источник тем же вызовом (читает → проставляет credibility/recency/bias → пишет `sources/NN.md` в свой диапазон номеров, `general-purpose` а не `Explore` — см. `subagents_v2.md`). Отдельного scoring pass нет. + --- ## Cost economics -Опираясь на pricing на момент написания (проверь актуальное в Anthropic Pricing): - -| Модель | Input $/1M | Output $/1M | Относительная цена | -|---|---|---|---| -| Haiku | $0.80 | $4.00 | 1x | -| Sonnet | $3.00 | $15.00 | ~3.75x | -| Opus | $15.00 | $75.00 | ~18.75x | +Цены на модели меняются быстрее, чем этот файл переписывается — проверяй актуальное в +Anthropic Pricing. Срез на 2026-07-07: -**Иллюстрация для deep ресёрча (~5 sub-agents):** - -Если всё на Opus: 5 × ~50k input + 5 × ~10k output = 250k input + 50k output = **$7.50** только на Phase 4. +| Модель | Model ID | Input $/1M | Output $/1M | Ratio vs Haiku | +|---|---|---|---|---| +| Haiku 4.5 | `claude-haiku-4-5` | $1.00 | $5.00 | 1× | +| Sonnet 5 | `claude-sonnet-5` | $3.00 (интро $2.00 до 2026-08-31) | $15.00 (интро $10.00) | 3× | +| Opus 4.8 | `claude-opus-4-8` | $5.00 | $25.00 | 5× | -То же на правильном routing: -- Phase 1 (reframing) Opus/high: 5k in + 2k out = **$0.23** -- Phase 3 (plan) Opus/medium: 8k in + 3k out = **$0.35** -- Phase 4 (5 sub-agents Haiku/low): 5 × (15k in + 3k out) = **$0.12** -- Phase 6 (adversarial) Opus/high: 30k in + 5k out = **$0.83** -- Phase 7 (synthesis) Sonnet/high: 60k in + 15k out = **$0.40** +**Главный сдвиг: Opus теперь всего 5× от Haiku** (было 18.75× при $15/$75). Держать Opus на Phase 1/Phase 6 — почти бесплатно. Экономить нужно на fan-out (N sub-agents в Phase 4), не на этих фазах. -**Total ~$1.93** против $7.50 — **в 4× дешевле**, а на критичных фазах (Phase 1, 6) даже **качество выше** потому что Opus/high действительно нужен. +**Иллюстрация (deep, ~5 sub-agents):** всё на Opus = 250k in + 50k out ≈ **$1.62** только на Phase 4. Правильный routing: Phase 1 Opus/high $0.075 + Phase 3 Opus/medium $0.115 + Phase 4 5×Haiku/low $0.15 + Phase 6 Opus/high $0.275 + Phase 7 Sonnet/high $0.405 = **~$1.02** total. Разница уже не в разах — но не экономить на Phase 1/6 остаётся правилом архитектурным (узкая задача = дешёвая модель), не ценовым. -(Цифры приблизительные — суть в порядке величин, не точных значениях.) +(Порядок величин, не точный прогноз — проверяй актуальные цены.) --- @@ -93,7 +90,7 @@ Phase 6 red-team суб-агенты: deep → opus/high; medium → sonnet/high ``` Agent({ - subagent_type: "Explore", + subagent_type: "general-purpose", // fetch+save нужен Write; Explore — только для read-only разведки model: "haiku", // или "sonnet" / "opus" description: "...", prompt: "..." diff --git a/references/runtime_verification.md b/references/runtime_verification.md index e325d8f..3577ef1 100644 --- a/references/runtime_verification.md +++ b/references/runtime_verification.md @@ -34,7 +34,7 @@ is written but not yet "done" until it carries a verification header. the count of `red_flag: true` results, and their source ids/urls. 3. **Insert a verification header** at the top of the final report, right under the - title (block F9 below). + title (block F10 below). 4. **Act on red flags — do not just report them.** For each OPEN source confirmed dead (likely hallucinated or stale URL): @@ -76,7 +76,7 @@ quote(s) per source. No re-fetch in the common case. - UNSUPPORTED → re-search for real support; if none, demote the thesis to Open Questions. A claim with no entailing source is not a finding. 4. Output a second integrity axis — `faithfulness_integrity = SUPPORTED / total` — - separate from liveness. The F9 header carries both. + separate from liveness. The F10 header carries both. 5. Depth gate: - `shallow` — optional. - `medium` — required; any UNSUPPORTED on a hypothesis-bearing claim blocks finish. @@ -85,7 +85,12 @@ quote(s) per source. No re-fetch in the common case. **Two axes, one verdict:** liveness (URL alive) × faithfulness (source backs claim). A citation counts as verified only if it passes BOTH. -## Block F9 — Verification header (add to `references/blocks/frame.md`) +## Block F10 — Verification header (add to `references/blocks/frame.md`) + +> Renumbered from F9 to F10 (2026-07-07): F9 was claimed by the `background` block +> (see `references/blocks/frame.md`) merged from the deepdive-v2 design doc before this +> header was actually implemented in `frame.md`. No functional change — same header, +> same content, next free slot. Rendered at the very top of the final report: @@ -124,7 +129,7 @@ Add to the "Workflow — 9 фаз" list, after Phase 6: ``` 6.5. **Verify** [`haiku`/low] — две оси: (1) **liveness** — `check_citations.py` (URL жив?), (2) **faithfulness** — entailment claim ⊨ цитата из `sources/NN.md` (источник реально - подтверждает тезис?). Вставить verification-header (F9), отработать флаги: re-search / + подтверждает тезис?). Вставить verification-header (F10), отработать флаги: re-search / demote claim / смягчить overclaim. medium: integrity < 0.70 ИЛИ UNSUPPORTED на гипотезе блокирует finish; deep: ноль red flags и ноль UNSUPPORTED. См. `references/runtime_verification.md`. ``` diff --git a/references/source_scoring.md b/references/source_scoring.md index bfc60d1..ca76a42 100644 --- a/references/source_scoring.md +++ b/references/source_scoring.md @@ -46,6 +46,50 @@ - Тема плохо исследована (тогда честно: «литературы по теме мало, выводы предварительные»). - Эхокамера / мы плохо ищем (тогда отдельный поиск с противоположным запросом). +## Claims-ledger — `claims.csv` + +С этой версии триангуляция трекается не только «в уме» при синтезе, а отдельным +артефактом-ledger рядом с `sources.csv`. Заполняется в Фазе 5 (см. `workflow.md`) +из index-строк и claim-кандидатов, которые вернули fetch sub-agents (см. +`subagents_v2.md`) — каждый агент сам замечает, какой тезис подтверждает его +подтема, и передаёт кандидат-строку, а не оставляет это на «вспомнить в конце». + +**Схема:** + +| Поле | Значение | +|---|---| +| `claim_id` | `CL1`, `CL2`, ... сквозная нумерация | +| `claim` | тезис одной строкой | +| `hypothesis` | `H1`-`H4` или `-` если тезис не привязан к гипотезе плана | +| `sources` | id источников через `;` (`s01;s07;s12`) | +| `source_types` | типы через `;`, тот же порядок что `sources` (`primary;academic;industry`) | +| `status` | `triangulated` \| `weak` \| `single-type` \| `contradicted` \| `data-insufficient` | +| `confidence` | `high` \| `medium` \| `low` | +| `primary_source` | `Y` \| `N` — есть ли среди sources хотя бы один Credibility=5 первичный | + +**Механическая триангуляция:** `status: triangulated` ⟺ ≥3 источника **И** ≥2 разных +типа в строке. Это проверяется подсчётом полей `sources`/`source_types`, не +повторным чтением содержания — отсюда `haiku`/low модель на этом шаге в +`model_routing.md`. + +**Primary-first правило:** `confidence: high` разрешён ТОЛЬКО если `primary_source: Y`. +Без первичного источника — потолок `medium`, даже если формально triangulated по +количеству и разнотипности. Причина: три вторичных пересказа одного и того же +первичного факта легко создают иллюзию независимого подтверждения. + +**Пример:** + +```csv +claim_id,claim,hypothesis,sources,source_types,status,confidence,primary_source +CL1,"Postgres logical replication handles N nodes without external tooling",H1,s01;s07;s12,primary;industry;academic,triangulated,high,Y +CL2,"CDC tooling adds >200ms p99 latency at scale",H2,s09;s14,industry;industry,single-type,medium,N +CL3,"Vendor X claims zero-downtime migration",-,s22,industry,weak,low,N +``` + +**Дыры (status ≠ triangulated) → gap-волна.** См. `workflow.md` Фаза 4.5: точечный +haiku/low агент на конкретную дыру, максимум 2 круга, иначе честно +`status: data-insufficient`. + ## Файл sources/NN_slug.md — шаблон Каждый источник = отдельный файл. Это долгосрочная память исследования — через месяц возвращаешься и видишь цитаты с метаданными без перечитывания отчёта. @@ -132,3 +176,5 @@ fetched: 2026-05-21 # дата извлечения - ❌ Помечать источник «total 12+» без пересчёта — пересчитывай явно. - ❌ Парафразить цитаты в `sources/NN.md` — только дословные. - ❌ Сжимать все источники в один файл — теряется поиск, переиспользование, ссылка из отчёта. +- ❌ Ставить `confidence: high` в `claims.csv` без primary-источника — нарушает primary-first правило, даже если формально 3+ источника разного типа. +- ❌ Оставлять строку `claims.csv` без статуса после первого прохода — прогони gap-волну (Фаза 4.5), максимум 2 круга, потом честно `data-insufficient`. diff --git a/references/subagents_v2.md b/references/subagents_v2.md index b2e492e..97ef546 100644 --- a/references/subagents_v2.md +++ b/references/subagents_v2.md @@ -7,26 +7,30 @@ ``` Главный поток (assistant): - формирует план, разбивает тему на подтемы + - назначает каждому агенту диапазон номеров источников (s01-s09, s10-s19, ...) - запускает суб-агентов в ОДНОМ сообщении (параллель) - - получает JSON выжимки - - дедуплицирует URLs - - ПИШЕТ файлы sources/NN.md из полученного JSON - - триангулирует, синтезирует - -Суб-агент (subagent_type=Explore): - - читает свой промпт + - получает ТОЛЬКО индекс-строки для sources.csv (URL/title/type/date/scores/ + subquestion_ids/файл) — не полные тексты + - мёржит sources.csv, дедуплицирует по URL между диапазонами + - заполняет claims.csv из индекс-строк + заявленных claim'ов + - триангулирует по claims.csv, синтезирует + +Суб-агент (subagent_type=general-purpose, свой диапазон NN): + - читает свой промпт (включая закреплённый диапазон номеров) - делает WebSearch + WebFetch - - оценивает источники по шкале - - возвращает структурированный JSON - - НЕ пишет файлы (Explore read-only) + - оценивает каждый источник по шкале сам (не отдельный scoring pass — H7) + - ПИШЕТ полные файлы sources/NN_slug.md в своём диапазоне (Write — параллельно, + без конфликтов, т.к. диапазоны не пересекаются) + - возвращает в главный поток ТОЛЬКО индекс-строки (компактно — полные тексты + источников через главный контекст не проходят) ``` -Так главный поток сохраняет контроль над файлами и дедупликацией, а суб-агенты — параллельны и не забивают контекст сырыми данными. +Так главный поток не раздувается сырыми текстами источников (только компактные индекс-строки), а параллельная запись `sources/NN.md` не конфликтует, потому что у каждого агента свой непересекающийся диапазон номеров. ## Какой subagent_type -- **`Explore`** — дефолт для deep-research. Read-only, имеет WebFetch/WebSearch, защищает основной контекст. Не может писать файлы — это ок, файлы пишет главный поток. -- **`general-purpose`** — только если подтема требует одновременно веб-поиска И чтения локальных файлов проекта (например, ресёрч под фичу с учётом существующего кода в репо). Имеет полный доступ. +- **`general-purpose`** — дефолт для fetch+save (Phase 4.1). Нужен `Write`, чтобы агент сам сохранял `sources/NN.md` в своём диапазоне номеров, а не передавал полные тексты обратно в главный поток. Каждому агенту — явный диапазон: агент №1 → `s01-s09`, №2 → `s10-s19`, и т.д. (см. промпт-шаблон ниже, поле `SOURCE ID RANGE`). +- **`Explore`** — только для чистой discovery-разведки БЕЗ сохранения файлов (например, Phase 3.5 capability discovery или предварительная разведка «сколько вообще есть материала» до того как решили дробить на подтемы). Как только агенту нужно писать `sources/NN.md` — это `general-purpose`, не `Explore`. - **`Plan`** — НЕ для поиска. В deep-research не использовать. ## Какую модель выбрать (model routing) @@ -50,7 +54,7 @@ ``` Agent({ - subagent_type: "Explore", + subagent_type: "general-purpose", // fetch+save нужен Write, см. выше model: "haiku", // ← важно: явный выбор description: "...", prompt: "..." @@ -82,6 +86,7 @@ Agent({ - `API ENDPOINTS TO USE` ← из той же секции 12 → конкретные API из `api_sources/` (с пометкой какие auth-env-vars нужны) - `DISCOVERY EXECUTED` ← из секции 12: что уже было найдено через awesome-lists registry / GitHub topics / HuggingFace на шаге 4.0 — суб-агент может на это опираться, не повторять discovery впустую - `CRITICAL GAPS` ← из секции 12 → critical gaps to address для этой подтемы +- `SOURCE ID RANGE` ← закреплённый за этим агентом диапазон номеров источников, назначает главный поток ПЕРЕД launch: агент №1 → `s01-s09`, №2 → `s10-s19`, №3 → `s20-s29`, и т.д. (шаг по 9-10 номеров с запасом). Диапазоны не пересекаются — это устраняет конфликты при параллельной записи `sources/NN.md`. Так главный поток не дублирует работу плана и обеспечивает прозрачность: пользователь в plan.md видит точно тот же brief что и агент. @@ -97,6 +102,10 @@ medium/deep depth, with structured JSON output requested. YOUR SUBTOPIC: +YOUR SOURCE ID RANGE: s-s (e.g. s10-s19). Use ONLY these numbers for the +files you write. Do not reuse a number outside your range — other agents are +writing in parallel with their own ranges. + BLOCKS THIS SUBTOPIC FEEDS: - : - : @@ -137,7 +146,8 @@ TASK: - 2-4 key direct quotes (verbatim, with location/page if possible) - Author, publication date, source type - How it relates to each hypothesis (supports / contradicts / neutral) -3. Score each source on three axes 1-5: +3. Score each source YOURSELF on three axes 1-5 (no separate scoring pass follows — + you are the one who read it, you score it): - Credibility: 5=primary/peer-review, 4=industry-authority, 3=quality general media, 2=expert blog, 1=forum/anon - Recency: 5=<1yr, 4=1-3yr, 3=3-5yr, 2=5-10yr, 1=>10yr (unless historical topic) @@ -145,36 +155,41 @@ TASK: 2=lobbyist, 1=propaganda 4. CRITICAL: include at least 1-2 sources representing OPPOSITION or CRITICISM of the dominant view in this subtopic. If you cannot find any — say so explicitly. - -OUTPUT FORMAT (strict JSON, no commentary outside JSON): +5. WRITE the full source file yourself: `sources/_.md` using the + template in `source_scoring.md`, with complete frontmatter (channel, access, + scores, subquestion_ids) and verbatim quotes. Use ONLY ids from your assigned + range (see YOUR SOURCE ID RANGE above). +6. For each claim/thesis this subtopic supports, note it as a candidate row for + `claims.csv` (claim text, hypothesis id if any, which source ids back it, source + types, whether at least one is Primary — the "primary_source" flag). + +OUTPUT FORMAT — return ONLY compact index rows to the main thread, NOT full source +text (full text already lives in the files you wrote in step 5). Strict JSON, no +commentary outside JSON: { "subtopic": "", "summary": "<3-5 sentence summary of what you found>", - "sources": [ + "source_index": [ { + "id": "s07", "url": "https://...", "title": "...", - "author": "...", - "date": "YYYY-MM-DD or YYYY", "type": "Primary|Academic|Industry-media|General-media|Expert-blog|Forum|Other", "channel": "", - "access": "OPEN|PARTIAL|paywalled-abstract-only|gray-area-source|closed", - "credibility": 5, - "recency": 4, - "bias": 4, - "total": 13, - "summary": "<2-3 sentence summary>", - "quotes": [ - {"text": "...", "location": "Section 2 / p.34"}, - {"text": "..."} - ], - "hypothesis_evidence": { - "H1": "supports — quote 1 directly states ...", - "H2": "contradicts — author argues opposite ...", - "H3": "neutral / not addressed" - }, - "notes": "" + "date": "YYYY-MM-DD or YYYY", + "credibility": 5, "recency": 4, "bias": 4, "total": 13, + "subquestion_ids": ["Q2"], + "file": "sources/07_.md" + } + ], + "claim_candidates": [ + { + "claim": "", + "hypothesis": "H1", + "sources": ["s07", "s09"], + "source_types": ["Primary", "Industry-media"], + "primary_source": true } ], "opposition_found": true, @@ -188,6 +203,8 @@ CONSTRAINTS: - If a source is paywalled / inaccessible — note it in `gaps` and try alternative. - Do not use bash/curl to bypass WebFetch restrictions. - If WebFetch fails for a URL — try alternative source, don't insist. +- Do NOT return full source text/quotes in your final JSON reply — they belong in + the files you wrote. Returning them again bloats the main thread's context. ``` ### RU template @@ -198,6 +215,9 @@ CONSTRAINTS: ТВОЯ ПОДТЕМА: <узкая подтема — что ищет ЭТОТ агент, не вся тема> +ТВОЙ ДИАПАЗОН НОМЕРОВ ИСТОЧНИКОВ: s-s (например s10-s19). Используй ТОЛЬКО +эти номера для своих файлов — другие агенты параллельно пишут в своих диапазонах. + ГИПОТЕЗЫ ДЛЯ ТЕСТИРОВАНИЯ: - H1: <опровергаемое утверждение> - H2: ... @@ -209,7 +229,8 @@ CONSTRAINTS: - 2-4 прямые цитаты (дословно, с указанием раздела/страницы если есть) - Автор, дата публикации, тип источника - Отношение к каждой гипотезе (supports / contradicts / neutral) -3. Оценить каждый источник по 3 осям 1-5: +3. Оценить каждый источник САМОМУ по 3 осям 1-5 (отдельного scoring-прохода не + будет — кто прочитал, тот и скорит): - Credibility: 5=первичный/peer-review, 4=отраслевая медиа, 3=качественная пресса, 2=экспертный блог, 1=форум/анон - Recency: 5=<1г, 4=1-3г, 3=3-5л, 2=5-10л, 1=>10л @@ -217,33 +238,41 @@ CONSTRAINTS: 2=лоббист, 1=пропаганда 4. КРИТИЧНО: включить ≥1-2 источника с противоположной позицией / критикой доминирующего взгляда. Если не нашёл — сказать прямо. +5. ЗАПИСАТЬ полные файлы `sources/_.md` самому (шаблон в + `source_scoring.md`), используя только номера из своего диапазона. +6. Для каждого тезиса, который подтверждает эта подтема, — кандидат-строка для + `claims.csv` (текст тезиса, гипотеза, какие sources подтверждают, их типы, + есть ли среди них primary source). -ФОРМАТ ВЫВОДА (строгий JSON, без комментариев вне JSON): +ФОРМАТ ВЫВОДА — вернуть в главный поток ТОЛЬКО компактные index-строки, НЕ полные +тексты источников (полный текст уже в файле из шага 5). Строгий JSON: -[см. EN шаблон выше — структура та же] +[см. EN шаблон выше — структура `source_index` + `claim_candidates` та же] ОГРАНИЧЕНИЯ: - Максимум 10 источников. Качество важнее количества. - Цитаты ДОСЛОВНЫЕ. Не пересказ. - Если источник за paywall — в `gaps`, искать альтернативу. - НЕ использовать bash/curl для обхода ограничений WebFetch. +- НЕ возвращать полные цитаты/тексты источников в финальном JSON — они уже в + записанных файлах, повторный возврат раздувает контекст главного потока. ``` ## После возврата суб-агентов — что делает главный поток -1. **Парсинг JSON.** Если суб-агент вернул мусор — попроси переслать в JSON, не интерпретируй сам. +1. **Парсинг JSON.** Если суб-агент вернул мусор — попроси переслать в JSON, не интерпретируй сам. Ожидай `source_index` (компактные строки) + `claim_candidates` — НЕ полные тексты источников (их агент уже записал сам, см. выше). -2. **Дедупликация по URL.** Если два суб-агента нашли один и тот же URL — это ОДИН источник, объединить quotes и evidence из обоих ответов. +2. **Дедупликация по URL.** Если два суб-агента нашли один и тот же URL под разными id (не должно случиться при непересекающихся диапазонах, но проверяй) — это ОДИН источник, оставить файл с лучшим scoring, вторую запись пометить дублем в `sources.csv`. -3. **Запись файлов `sources/NN_slug.md`.** Для каждого уникального source создать файл по шаблону из `source_scoring.md`. Нумерация сквозная, не сбрасывается. +3. **Мёрж `sources.csv`** из всех `source_index` — файлы уже на диске (агенты сами их записали в своих диапазонах), главный поток здесь только сводит индекс, не переписывает `sources/NN.md`. -4. **Обновление `sources.csv`.** Все источники из всех суб-агентов с пересчитанным total. +4. **Заполнение `claims.csv`** из всех `claim_candidates` (Phase 5 — см. `source_scoring.md` раздел claims-ledger). Смёржить дублирующиеся claim'ы от разных агентов (если тезис один и тот же — объединить sources/source_types в одну строку). 5. **Проверка покрытия:** - Сколько типов источников? (нужно ≥4) - Найдена ли оппозиция? (нужна минимум одна) - Все ли гипотезы получили evidence? (нужно ≥3 источника на гипотезу) - - Если что-то не покрыто — отдельный round доп-поиска (без суб-агентов, в основном потоке, целевыми запросами). + - Сколько строк `claims.csv` НЕ triangulated? → это вход в gap-волну (Phase 4.5, см. `workflow.md`). ## Антипаттерны @@ -251,8 +280,9 @@ CONSTRAINTS: - ❌ Дать слишком общий промпт «ищи про X» — вернётся жидкая выжимка. Подтема должна быть УЗКОЙ. - ❌ Запустить суб-агентов последовательно (Agent call → ждать → следующий). Только параллельно в одном сообщении. - ❌ Принимать выжимку суб-агента как финал без проверки. Дедуплицируй URLs и проверь scoring. -- ❌ Использовать `general-purpose` когда хватает `Explore`. Explore быстрее и дешевле. -- ❌ Просить суб-агента ПИСАТЬ файлы — Explore не умеет. Главный поток пишет. +- ❌ Использовать `Explore` когда агенту нужно писать `sources/NN.md` — Explore read-only, не сохранит файл. Для fetch+save всегда `general-purpose`. +- ❌ Не назначить агенту диапазон номеров ПЕРЕД launch — без этого параллельная запись рискует коллизией id. +- ❌ Просить суб-агента вернуть полные тексты/цитаты источников в JSON-ответе — раздувает контекст главного потока. Полный текст живёт в файле, в главный поток идёт только index-строка. - ❌ Пропустить требование «найди оппозицию» — суб-агенты по умолчанию ищут confirmation, не contradiction. ## Когда НЕ запускать суб-агентов diff --git a/references/workflow.md b/references/workflow.md index 13e861d..0de987b 100644 --- a/references/workflow.md +++ b/references/workflow.md @@ -196,11 +196,11 @@ time_box_hard: Какая подтема собирает evidence для каких блоков. Без этого агенты не знают для чего работают. -| Subtopic | Под какие блоки | Кому (Explore # / main thread) | +| Subtopic | Под какие блоки | Кому (agent # + source range / main thread) | |---|---|---| -| ST1: <название> | F3, E1, E4 | Explore #1 | -| ST2: <название> | A1 (data-table rows), M2 (profile cards) | Explore #2 | -| ST3: <название> | V2 (evidence FOR/AGAINST), Z1 (counter-args) | Explore #3 | +| ST1: <название> | F3, E1, E4 | Agent #1 (`general-purpose`, s01-s09) | +| ST2: <название> | A1 (data-table rows), M2 (profile cards) | Agent #2 (`general-purpose`, s10-s19) | +| ST3: <название> | V2 (evidence FOR/AGAINST), Z1 (counter-args) | Agent #3 (`general-purpose`, s20-s29) | | ST4: <название> | E10 (failure modes), Z2 (open questions) | main thread | ## 12. Information sourcing strategy @@ -521,20 +521,37 @@ deep ≤2, shallow never (fixed outline). Don't silently rewrite structure — e revision is a recorded, budgeted decision, same as any deviation. This keeps the report shape adaptive to what the evidence actually is, not what we guessed at Phase 2. -## Фаза 5. Скоринг и триангуляция +## Фаза 5. Claims-ledger и триангуляция -**Model:** scoring per source — `haiku` / `low` (простой rubric). Triangulation check — `sonnet` / `medium` (требует понимания содержания). +**Model:** сборка `claims.csv` из index-строк — `haiku` / `low` (механическая работа). Triangulation check — `haiku` / `low` (правило механическое, см. ниже — не требует "понимания" содержания, только подсчёта источников/типов по строке). -Каждый источник в `sources/NN.md` имеет frontmatter со scoring (см. `source_scoring.md`). +**Скоринг источников больше не отдельный шаг.** Каждый источник в `sources/NN.md` уже имеет заполненный frontmatter со scoring — его проставил fetch sub-agent на шаге 4.1, в момент когда читал источник (H7-правило: скорит тот, кто читал). Здесь, в Фазе 5, шкала подробно описана в `source_scoring.md` для справки, но повторного прохода по всем источникам не требуется. -**Triangulation rule:** каждое утверждение в финальных выводах подтверждено ≥3 независимыми источниками **разного типа**. Не три статьи одного автора, не три новости одного издания. +**Claims-ledger (`claims.csv`)** — новый артефакт-ledger рядом с `sources.csv`. Схема: -**Если триангуляция не сходится:** -- < 3 источников → пометь тезис «спорно / требует проверки», confidence: low -- 3 источника, но одного типа → «требует подтверждения первичным источником», confidence: medium -- Нашёл оппозицию → отдельный counter-argument в Фазу 5 +``` +claim_id, claim, hypothesis, sources, source_types, status, confidence, primary_source +``` + +- `claim` — тезис одной строкой. +- `hypothesis` — H1-H4 или `-` если не привязан к гипотезе. +- `sources` — список id (`s01;s07;s12`). +- `source_types` — типы источников через `;` (`primary;academic;industry`). +- `status` — `triangulated | weak | single-type | contradicted | data-insufficient`. +- `confidence` — `high | medium | low`. +- `primary_source` — `Y | N`. + +**Заполнение:** главный поток собирает `claims.csv` из `claim_candidates`, которые вернул каждый fetch sub-agent (см. `subagents_v2.md`), плюс из явного чтения claims в уже записанных `sources/NN.md`. Дублирующиеся claim'ы от разных агентов — смёржить в одну строку (объединить `sources`/`source_types`). -**После скоринга** — обнови `sources.csv`: +**Triangulation rule (механическая):** строка получает `status: triangulated`, если ≥3 источника **И** ≥2 разных типа. Иначе: +- < 3 источников → `status: weak`, confidence: low +- ≥3 источника, но один тип → `status: single-type`, confidence: medium (max) +- Явное противоречие между источниками → `status: contradicted` — отдельный counter-argument (Z1) +- После gap-волны (см. выше) всё ещё не закрыто → `status: data-insufficient` (честный результат, не скрывать) + +**Primary-first правило:** ключевое число/факт без хотя бы одного primary-источника (`primary_source: N`) не может получить `confidence` выше `medium`, даже если формально triangulated по количеству/разнотипности. Primary здесь — filing, официальная дока, датасет, оригинальное исследование (см. Credibility=5 в `source_scoring.md`). + +**После сборки** — обнови `sources.csv` (индекс источников, как раньше) и новый `claims.csv`: ```csv №,URL,Title,Type,Author,Date,Credibility,Recency,Bias,Total,Used,File,Note @@ -542,17 +559,42 @@ shape adaptive to what the evidence actually is, not what we guessed at Phase 2. 2,https://...,Industry benchmark,Industry-media,J. Smith,2026-02,4,5,4,13,Y,sources/02_industry.md,Supports H1 ``` +```csv +claim_id,claim,hypothesis,sources,source_types,status,confidence,primary_source +CL1,"Logical replication scales to N nodes without external tooling",H1,s01;s07;s12,primary;industry;academic,triangulated,high,Y +CL2,"CDC adds >200ms p99 latency at scale",H2,s09;s14,industry;industry,single-type,medium,N +``` + +### Gap-волна (Фаза 5 продолжается — не новая фаза, аналогично loop-конвенции Фазы 4) + +**Model:** `haiku` / `low`. Узкая точечная задача на конкретную дыру — дорогая модель не нужна. + +После первого заполнения `claims.csv` собери список дыр — строки со `status ≠ triangulated`. + +**Точечная вторая волна:** по одному агенту на дыру (или пачкой, параллельно), промпт = конкретный claim + чего конкретно не хватает: +- «нужен primary-источник для CL2» +- «нужен 3-й тип источника, сейчас только industry×2» +- «противоречие между s09 и s14 — найти причину или дополнительный арбитр» + +**Максимум 2 круга.** Если после второго круга дыра не закрылась — строка помечается `status: data-insufficient`. Это честный результат отчёта, не провал: попадает в Open Questions (Z2), а не маскируется. + +**Выход:** обновлённый `claims.csv`, обновлённые `sources/NN.md` (новые источники в свежем диапазоне номеров — следующий свободный блок после уже занятых). + ## Фаза 6. Синтез + multi-angle red team **Model:** red-team суб-агенты — `opus` / `high` **(обязательно для deep)**, `sonnet` / `high` для medium. Synthesis assembly — `sonnet` / `high` (длинный контекст). Не экономить на red team — это где Haiku/Sonnet делают soft-pushback без реальной атаки на гипотезы. **Порядок:** -1. Перечитай ВСЕ `sources/NN.md` с `used: Y`. Не делай синтез из памяти. -2. Перечитай `plan.md` — жанр, blocks, гипотезы. +1. Перечитай ВСЕ `sources/NN.md` с `used: Y`. Не делай синтез из памяти. Для **deep**: `findings/` слой обязателен — синтез идёт из `findings/` + `claims.csv`, точечная сверка `sources/NN.md` только по спорным местам. Для shallow/medium — как раньше, перечитать used sources целиком. +2. Перечитай `plan.md` (жанр, blocks, гипотезы, секция 0 User context) и `claims.csv` (статус/confidence каждого тезиса). 3. Загрузи нужные категорийные файлы `blocks/*.md` (только те что нужны для выбранных blocks). Прогрессивно — не сразу все. 4. Для каждой гипотезы — собери поддерживающие/опровергающие цитаты. Опционально вынеси крупные в `findings/FN.md` (см. `blocks/close.md` блок Z6). -5. Собери черновик `_.md` из выбранных блоков по порядку из `plan.md`. Каждый блок — по шаблону из своего категорийного файла. -6. **Multi-angle red team** (см. `adversarial_pass.md`) — draft → claim ledger → N враждебных ролей (Skeptic/Contrarian/Gap-hunter) как `general-purpose` суб-агенты → триаж severity → ОДИН раунд ремедиации HIGH → финал. Гейт глубины: shallow=R1 инлайн, medium=R1+R2, deep=R1+R2+R3. Дефекты → counter-arguments (`Z1`) + Open Questions; лог в `findings/redteam_.md`. Не маскируй несогласие. +5. Собери черновик `_.md` из выбранных блоков по порядку из `plan.md`. Каждый блок — по шаблону из своего категорийного файла. Три сквозных правила синтеза (применяй ко всем блокам, не только TL;DR): + - **Числа с якорем сравнения.** Ключевое число без базы сравнения запрещено: «Рынок $4.5B» — недостаточно. «Рынок $4.5B — втрое меньше соседнего сегмента X, растёт втрое быстрее среднего по индустрии» — годится. Якорь: vs база / vs сосед / vs динамика во времени. + - **Условия применимости.** Каждый вывод — с явным «когда верен, когда нет», не голое утверждение. + - **Confidence из claims.csv.** Каждый пункт TL;DR (F1) несёт свой `confidence` (high/medium/low), взятый из соответствующей строки `claims.csv` — не придуманный на глаз при синтезе. + - Блок Z12 `so-what-for-you` (см. `blocks/close.md`) собирается на этом же шаге из `plan.md` секции 0 (User context) + `claims.csv` — проекция выводов на кейс пользователя, до `actionable-next-steps`. +6. **Multi-angle red team** (см. `adversarial_pass.md`) — draft → claim ledger (внутренний список falsifiable-тезисов для red team, не путать с файлом `claims.csv`) → N враждебных ролей (Skeptic/Contrarian/Gap-hunter) как `general-purpose` суб-агенты → триаж severity → ОДИН раунд ремедиации HIGH → финал. Гейт глубины: shallow=R1 инлайн, medium=R1+R2, deep=R1+R2+R3. Дефекты → counter-arguments (`Z1`) + Open Questions; лог в `findings/redteam_.md`. Не маскируй несогласие. 5-й adversarial-вопрос (см. `adversarial_pass.md`): есть ли числа без якоря сравнения, выводы без Z12-проекции, рекомендации без trade-off/kill-criteria? 7. Если в системе есть `anthropic-skills:humanizer-ru` — прогони финальный отчёт через него. 8. Сохрани финальный отчёт. @@ -585,6 +627,8 @@ shape adaptive to what the evidence actually is, not what we guessed at Phase 2. - [ ] **Acceptance criteria из plan.md (секция 4) ВСЕ выполнены** — перепроверь каждый чек-бокс - [ ] Все `sources/NN.md` имеют корректный frontmatter (scoring, channel, access заполнены) - [ ] `sources.csv` обновлён, total пересчитан +- [ ] `claims.csv` заполнен — каждая строка имеет status; строки не triangulated прошли gap-волну (см. Фаза 5, max 2 круга) и честно помечены `data-insufficient` если не закрылись +- [ ] Ни один тезис с `confidence: high` не нарушает primary-first правило (без primary-источника confidence ≤ medium) - [ ] `plan.md` имеет `status: completed` - [ ] `plan.md` секция 15 (notes) финализирована — все важные observations документированы - [ ] `_.md` собран из всех блоков из `plan.md` → `blocks:` diff --git a/runner/DESIGN.md b/runner/DESIGN.md index a1a0df8..f74dfb3 100644 --- a/runner/DESIGN.md +++ b/runner/DESIGN.md @@ -11,7 +11,7 @@ two genuinely Claude-specific pieces are: `complete()` calls), so the methodology no longer depends on the harness. 2. **Source-file management** — the skill relies on the agent writing `sources/NN.md`. -Everything else (the 9-phase methodology, 103 blocks, 29 channels, 460+ sources, the +Everything else (the 9-phase methodology, 105 blocks, 29 channels, 460+ sources, the scoring rubric) is model-agnostic markdown. If a thin runner owns the fan-out and the file I/O and talks to *any* model through one interface, the skill becomes infrastructure instead of a Claude add-on. That is the difference between "a skill" diff --git a/scripts/context_budget.py b/scripts/context_budget.py index 486960c..cc59c67 100644 --- a/scripts/context_budget.py +++ b/scripts/context_budget.py @@ -55,7 +55,10 @@ def check_proxy_in_sync(root: Path) -> str | None: # Budgets in tokens. Tune as the catalog evolves; these are the guard-rails CI enforces. BUDGET_SKILL_MD = 7500 # SKILL.md is read on EVERY invocation — keep it lean -BUDGET_ALWAYS_FLOOR = 55000 # the "base refs" SKILL.md says to always load for medium/deep +BUDGET_ALWAYS_FLOOR = 56000 # the "base refs" SKILL.md says to always load for medium/deep +# Raised from 55000 on 2026-07-07: claims.csv artifact + gap-wave loop (Phase 5) + 2 +# new report blocks (F9 background, Z12 so-what-for-you) added durable value at a +# modest, deliberately-trimmed floor cost (~1200 tok). See docs/2026-07-07-v2-design.md. # Files SKILL.md marks as "Базовые (всегда)" — the unavoidable floor for a medium/deep run. ALWAYS_LOAD = [ diff --git a/tests/test_catalog_counts.py b/tests/test_catalog_counts.py index 6586e7f..03a78d6 100644 --- a/tests/test_catalog_counts.py +++ b/tests/test_catalog_counts.py @@ -9,11 +9,11 @@ def test_counts_match_verified_ground_truth(): - """Golden numbers re-verified by regex on 2026-06-13. If the catalog grows, - update these intentionally — a mismatch here means either the catalog changed - or a regex broke.""" + """Golden numbers re-verified by regex on 2026-07-07 (blocks: +F9 background, + +Z12 so-what-for-you). If the catalog grows, update these intentionally — a + mismatch here means either the catalog changed or a regex broke.""" c = catalog_counts.counts(REPO) - assert c["blocks"] == 103 + assert c["blocks"] == 105 assert c["channels"] == 29 assert c["stat_sources"] == 460 assert c["api"] == 39 diff --git a/tests/test_stamp_docs.py b/tests/test_stamp_docs.py index 213b16c..0835235 100644 --- a/tests/test_stamp_docs.py +++ b/tests/test_stamp_docs.py @@ -57,7 +57,7 @@ def test_render_values_has_all_keys(): "count:genres", "count:phases", "phases:list:ru", "phases:table:en"): assert k in v - assert v["count:blocks"] == "103" + assert v["count:blocks"] == "105" assert v["count:phases"] == "9" @@ -65,14 +65,14 @@ def test_check_mode_detects_drift(tmp_path): f = tmp_path / "doc.md" f.write_text("n=75", encoding="utf-8") rc = stamp_docs.run(REPO, [f], write=False) - assert rc == 1 # 75 != 103 → drift + assert rc == 1 # 75 != 105 → drift def test_write_mode_fixes_and_check_passes(tmp_path): f = tmp_path / "doc.md" f.write_text("n=75", encoding="utf-8") assert stamp_docs.run(REPO, [f], write=True) == 0 - assert "103" in f.read_text(encoding="utf-8") + assert "105" in f.read_text(encoding="utf-8") assert stamp_docs.run(REPO, [f], write=False) == 0 # now synced @@ -87,7 +87,7 @@ def test_zero_count_refused(monkeypatch, tmp_path): def test_unused_key_warns_not_fails(tmp_path, capsys): # a doc using only ONE key → the other keys are "stamped nowhere" → WARNING, rc 0 f = tmp_path / "doc.md" - f.write_text("n=103", encoding="utf-8") + f.write_text("n=105", encoding="utf-8") rc = stamp_docs.run(REPO, [f], write=False) out = capsys.readouterr().out assert rc == 0 # warning, not drift