--- name: multi-source-research description: "Pipeline for grounded research: gather (≥2 sources) → conflict-detect → synthesize-with-provenance. Cites K2 §3.1 (provenance per claim) + K2 §3.2 (multiview retrieval). Reuses the brainstorming (commit ebd136a) as the canonical provenance shape; reuses conflict-detector agent (this plugin) as the contradiction step. 多源研究管道：採集（≥2源）→衝突檢測→帶溯源綜合。 Use when: synthesizing claims from multiple docs/repos/papers, before writing a load-bearing assertion in a spec or design doc, fact-checking a load-bearing PR description, gathering evidence for an architectural decision, validating a claim that contradicts a Phase 0 high-confidence bullet. Skip when: a single authoritative source is sufficient (e.g., 'what is this function's signature' answered by lci:get_context alone), or the claim is non-load-bearing (typo fix, comment update)." --- # Multi-Source Research Skill Grounded-research pipeline. Default to **prefer ≥2 sources** for any load-bearing claim; route them through the conflict-detector before synthesizing; carry provenance through to the output. The pipeline is the value — single-source shortcuts are the failure mode this skill exists to prevent. ## Provenance - **K2 design doc:** `docs/research/K2-knowledge-hygiene-from-papers.md` §3.1 (provenance per claim) + §3.2 (multiview retrieval rationale) - **Source papers:** OmniMEM (`2604.01007`) for provenance-per-claim; RAGSearch (`2604.09666`) for multiview retrieval complementary-roles finding - **Reused contract:** brainstorming `` block (commit `ebd136a`) defines the 5 provenance value forms — this skill emits the same shape, no parallel schema. - **Reused agent:** `conflict-detector` (this plugin, `agents/conflict-detector.md`) is the contradiction step. ## Pipeline ``` ┌───────────────────────────┐ │ Step 1 — Gather sources │ │ prefer ≥2; minimum 2 │ │ for load-bearing claims │ └──────────────┬────────────┘ │ ▼ ┌───────────────────────────┐ │ Step 2 — Conflict-detect │ │ invoke conflict-detector │ │ agent on the source set │ └──────────────┬────────────┘ │ ▼ ┌───────────────────────────────┐ │ Step 3 — Synthesize │ │ with-provenance │ │ each output claim carries the │ │ tag(s) │ │ that ground it │ └───────────────────────────────┘ ``` ## Step 1 — Gather **Input contract:** the topic / claim to ground, plus the load-bearing-ness signal (load-bearing → ≥2 sources required; non-load-bearing → escape valve below). **Process:** 1. Decide the **source classes** appropriate for the claim: - **Code claims** → `mcp__plugin_lci_lci__search` for symbols + `Read` for context lines. - **Behavioral / runtime claims** → code source + at least one doc / test source. - **External / API / library claims** → official docs + at least one usage example in this codebase (or a second authoritative source if not used here). - **Decision / preference claims** → memory entries (`.dartai/memory/`, `CLAUDE.md`) + commit history (`git log`). 2. Gather **at least 2 sources** unless the escape valve applies. 3. For each gathered source, record the source record per the conflict-detector input contract: ```json { "id": "", "source_text": "", "provenance": "", "confidence": "" } ``` **Escape valve — single source acceptable when:** - The claim is **non-load-bearing** (won't change a downstream decision; e.g., "what's the function signature" before a typo fix). - A single source is **structurally authoritative and uncontested** (e.g., the language spec for a syntax question; the source-of-truth schema file for a field type). When the escape valve fires, emit a `single-source-by-design` note in the output so reviewers can audit the choice. Do NOT silently degrade. **Output contract of Step 1:** an array of source records, length ≥ 2 (or length 1 with `single-source-by-design` note). ## Step 2 — Conflict-detect **Input contract:** the source-records array from Step 1. **Process:** 1. If length < 2 (escape-valve case), skip Step 2; record `conflict_check: skipped, reason: single-source-by-design`. 2. Otherwise, invoke the `conflict-detector` agent (this plugin, `agents/conflict-detector.md`) with the source-records array. 3. Receive the structured JSON output (see conflict-detector's Output Contract). **Branching on the result:** | `conflict_type` | Step 3 behavior | |---|---| | `no-conflict` | Proceed to synthesize. Carry all source provenance into the output. | | `direct-contradiction`, `numeric-mismatch`, `temporal-mismatch`, `scope-mismatch` | Apply the agent's `recommended_resolution`. If `escalate-to-user`, **stop and surface the conflict-detector output verbatim** before any synthesize attempt. | | `no-entity-match` | Treat as Step-1 error (caller selected non-overlapping sources). Re-gather with tighter entity selection. | | `insufficient-sources` | Should not occur here (Step 1 enforces ≥2). If it does, treat as a contract bug — log and re-gather. | **Output contract of Step 2:** the conflict-detector JSON output (or the skipped-marker for the escape-valve case). ## Step 3 — Synthesize-with-provenance **Input contract:** the source-records array (Step 1) + the conflict-detector output (Step 2). **Process:** 1. Write the synthesized claim(s) as **bullets**, mirroring the Phase 0 architect-summary shape from `ebd136a`. 2. Each bullet carries a `provenance` field per the `` (one of: `file::` | `memory:` | `git:` | `web:` | literal `guess`). Multi-source bullets may carry multiple provenance tags as a list. 3. **Empty-handling rule (mirrors ``):** never omit `provenance`. If a bullet is unsupported by any gathered source — i.e., it is your synthesis-level inference — label it literal `guess`. Do not silently elevate inference to grounded claim. 4. If Step 2 returned a contradiction with `recommended_resolution: prefer-recent` or `prefer-authoritative`, the synthesized bullet: - Carries the winning source's provenance. - Adds an `overridden` field naming the losing source's id and the driving signal (one sentence). - Mirrors the brainstorming `Conflict-Detect Integration` audit-trail subsection from `ebd136a`: spec-level conflicts get an explicit "conflicting signal acknowledged and overridden" note, never a silent drop. **Output shape (canonical):** ```json { "synthesis": [ { "claim": "", "provenance": ["file:src/cache.ts:42", "git:abc1234"], "overridden": null }, { "claim": "", "provenance": "guess", "overridden": null }, { "claim": "", "provenance": ["file:src/cache.ts:42"], "overridden": { "loser_id": "docs/cache.md", "signal": "implementation file authoritative over docs for runtime behavior" } } ], "sources_consulted": [ {"id": "src/cache.ts:42", "provenance": "file:src/cache.ts:42", "confidence": "high"}, {"id": "docs/cache.md", "provenance": "file:docs/cache.md:14", "confidence": "high"} ], "conflict_check": { "ran": true, "result": "" } } ``` The `synthesis[].provenance` shape may be either a single string (single source) or an array (multi-source). The `` tag-vocabulary is identical; only cardinality differs. ## When This Skill Invokes the Conflict-Detector | Trigger | What flows to conflict-detector | |---|---| | Step 2 with ≥2 sources | the Step 1 source-records array | | Caller's escape-valve overrides single-source default | conflict-detector NOT invoked; `conflict_check: skipped` recorded | | Caller is `verify-claims` command | one invocation per load-bearing claim in the target doc/PR | | Caller is brainstorming Phase 1/2 surface-then-proceed | one invocation with the user's strategy pick + the conflicting Phase 0 bullet packaged as 2 sources | ## Anti-Patterns - **Single-source synthesis without escape-valve declaration** — if the claim is load-bearing and you skipped the gather-≥2 step, you have shipped an ungrounded assertion. Either gather more sources or explicitly invoke the escape valve with a recorded note. - **Provenance omission** — every synthesis bullet must carry `provenance`. Literal `guess` is the soft-fail; omission is the hard-fail. - **Silent override** — if conflict-detector returned `prefer-recent` / `prefer-authoritative`, the losing source must appear in the bullet's `overridden` field. Dropping it without acknowledgement is the brainstorming `Silent Rationalization Through Conflict` anti-pattern reified at the research layer. - **Skipping Step 2 because "the sources obviously agree"** — they may. Run Step 2 anyway when length ≥ 2; the cost is one agent call and the audit trail is worth it. ## Soft Guidance — Per-Claim Source Counts Default toward **2 sources** for load-bearing claims. Prefer **3+ sources** when the claim is high-stakes (security-sensitive, breaking-change-implying, or contradicts a Phase 0 high-confidence bullet). The agent never enforces a hard maximum — gather what the claim warrants, but document why you stopped. ## Forward References - **Multiview retrieval skill** (`TPqYid2TykLc`, deferred Tier-3) — will provide source-class diversity (dense + bm25 + symbolic + KG) for Step 1's gather. Until it lands, Step 1's source-class menu above is the baseline. - **Citation-verifier agent** (`qvd3VBUROdw2`, deferred Tier-3) — will retroactively verify the `provenance` tags emitted by Step 3 (file:line still resolves, web:url still loads, git:sha still in history).