---
name: source-comparison
description: Compare multiple sources on a topic and produce a grounded comparison matrix. Use when the user asks to compare papers, tools, approaches, frameworks, or claims across multiple sources.
---

# Source Comparison

Build a side-by-side comparison matrix grounded in primary sources, distinguishing agreement, disagreement, and uncertainty.

Derive a short slug from the comparison topic (lowercase, hyphens, ≤5 words). All files use this prefix.

## Subagent mapping

See `../_platform-mapping.md`. Use `researcher` for evidence gathering, `verifier` for citation verification.

## Workflow

### 1. Plan

Write `outputs/.plans/<slug>.md`:

- **Items being compared** — name them exactly (paper A vs paper B, tool X vs tool Y, etc.)
- **Dimensions of comparison** — 4–8 concrete axes (claim, evidence type, methodology, benchmark, caveats, confidence, etc.)
- **Source expectations** — what primary source is required for each cell
- **Output structure** — matrix columns and rows

Summarize briefly to the user, continue immediately unless they asked for plan review.

### 2. Gather

- **Narrow comparison (2–3 items, clear primary sources):** lead agent gathers directly.
- **Broad comparison (5+ items, or wide surface area):** dispatch `researcher` subagents, one per item or per dimension, each writing to `<slug>-research-<item>.md`.

Require primary sources. Reject blog posts that themselves cite unverifiable claims.

### 3. Build the matrix

One row per item, one column per dimension. Every cell must be traceable to a source.

Markdown table pattern:

```markdown
| Item | Key claim | Evidence type | Methodology | Caveats | Confidence |
|------|-----------|---------------|-------------|---------|-----------|
| ...  | ...       | ...           | ...         | ...     | ...       |
```

Follow the matrix with:

- **Agreement section** — dimensions where items converge
- **Disagreement section** — dimensions where items diverge, with the specific split named
- **Uncertainty section** — dimensions where primary sources don't settle it

### 4. Charts

- Quantitative dimensions → Mermaid bar chart, or CSV in `outputs/.notes/<slug>-data.csv`. No invented numbers.
- Method/architecture differences → Mermaid `graph TD`.

### 5. Cite

Dispatch `verifier` subagent to add inline citations and verify every URL in the comparison draft. Output to `outputs/.drafts/<slug>-cited.md`.

### 6. Deliver

Save final comparison to `outputs/<slug>-comparison.md`. End with a `Sources` section containing direct URLs for every source used.

Write `outputs/<slug>-comparison.provenance.md` with the same format as other research artifacts (see `literature-review` skill for the template).

## What NOT to compare

- Versions of the same thing that only differ in config — that's a benchmark, not a source comparison.
- Items without public primary sources — say so in the plan and stop.
