multi-source-research

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 <PROVENANCE-CONTRACT> (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 <PROVENANCE-CONTRACT> 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 │
              │ <PROVENANCE-CONTRACT> 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:

   {
     "id": "<stable id>",
     "source_text": "<verbatim or trimmed excerpt>",
     "provenance": "<file:path:line | memory:id | git:sha | web:url | guess>",
     "confidence": "<high | med | low>"
   }
   

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 <PROVENANCE-CONTRACT> (one of: file:<path>:<line> | memory:<id> | git:<sha> | web:<url> | literal guess). Multi-source bullets may carry multiple provenance tags as a list.
3. Empty-handling rule (mirrors <PROVENANCE-CONTRACT>): 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):

{
  "synthesis": [
    {
      "claim": "<the synthesized assertion>",
      "provenance": ["file:src/cache.ts:42", "git:abc1234"],
      "overridden": null
    },
    {
      "claim": "<another synthesized assertion>",
      "provenance": "guess",
      "overridden": null
    },
    {
      "claim": "<an assertion that resolved a conflict>",
      "provenance": ["file:src/cache.ts:42"],
      "overridden": {
        "loser_id": "docs/cache.md",
         
      
    
  
   
         
         
  
   
     
     
  

The synthesis[].provenance shape may be either a single string (single source) or an array (multi-source). The <PROVENANCE-CONTRACT> 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).