Summary
The README carries two overlapping framework-comparison tables (one under "How is this different from LangChain / LangGraph / Prefect / Dagster / Temporal?" and another under "How ChainWeaver relates to neighbours"). Merge them into a single canonical comparison and link to docs/comparisons.md for the full matrix, removing the duplication.
Why this matters
Two tables comparing the same tools invite drift (they can disagree after one is updated) and lengthen an already-long README, diluting the 30-second-clarity goal that closed #66 established. A single table that defers detail to docs/comparisons.md keeps the README scannable and the comparison authoritative in one place.
Current evidence
README.md line ~183: table headed "How is this different from LangChain / LangGraph / Prefect / Dagster / Temporal?".README.md line ~222: a second comparison table under "How ChainWeaver relates to neighbours" with overlapping columns (ChainWeaver, LangChain LCEL, Prefect 3, Dagster, Temporal, LangGraph).- Both already point to
docs/comparisons.md as the full matrix (lines ~191, ~233), so the canonical home exists.
External context
Not required for this issue.
Proposed implementation
- Decide the single best framing (recommend the "Is this for me?" decision angle) and merge the distinguishing rows from both tables into one.
- Remove the redundant table; keep a single prominent link to
docs/comparisons.md and the hosted comparisons page.
- Verify no other doc references the removed heading anchor (fix links if so).
AI-agent execution notes
Inspect README.md (both table regions and surrounding headings), docs/comparisons.md (ensure it remains the full matrix), any in-repo links to the removed section anchor (grep -rn "relates-to-neighbours\|how-is-this-different"). Preserve closed #66's 30-second-clarity intent. Keep neutral comparison wording (never imply another tool is superior/inferior).
Acceptance criteria
- README contains exactly one framework-comparison table.
- All internal links to the removed section are updated or removed.
docs/comparisons.md remains the linked full matrix.
Test plan
Markdown link-check (docs CI), manual README render review on GitHub.
Documentation plan
README.md edit, CHANGELOG (docs note); verify docs/comparisons.md cross-links.
Migration and compatibility notes
Not expected to require migration; one section anchor is removed (update any deep links).
Risks and tradeoffs
Low risk; only consideration is preserving every genuinely distinct comparison row when merging. Keep all neutral.
Suggested labels
documentation, refactor
Summary
The README carries two overlapping framework-comparison tables (one under "How is this different from LangChain / LangGraph / Prefect / Dagster / Temporal?" and another under "How ChainWeaver relates to neighbours"). Merge them into a single canonical comparison and link to
docs/comparisons.mdfor the full matrix, removing the duplication.Why this matters
Two tables comparing the same tools invite drift (they can disagree after one is updated) and lengthen an already-long README, diluting the 30-second-clarity goal that closed #66 established. A single table that defers detail to
docs/comparisons.mdkeeps the README scannable and the comparison authoritative in one place.Current evidence
README.mdline ~183: table headed "How is this different from LangChain / LangGraph / Prefect / Dagster / Temporal?".README.mdline ~222: a second comparison table under "How ChainWeaver relates to neighbours" with overlapping columns (ChainWeaver, LangChain LCEL, Prefect 3, Dagster, Temporal, LangGraph).docs/comparisons.mdas the full matrix (lines ~191, ~233), so the canonical home exists.External context
Not required for this issue.
Proposed implementation
docs/comparisons.mdand the hosted comparisons page.AI-agent execution notes
Inspect
README.md(both table regions and surrounding headings),docs/comparisons.md(ensure it remains the full matrix), any in-repo links to the removed section anchor (grep -rn "relates-to-neighbours\|how-is-this-different"). Preserve closed #66's 30-second-clarity intent. Keep neutral comparison wording (never imply another tool is superior/inferior).Acceptance criteria
docs/comparisons.mdremains the linked full matrix.Test plan
Markdown link-check (docs CI), manual README render review on GitHub.
Documentation plan
README.mdedit, CHANGELOG (docs note); verifydocs/comparisons.mdcross-links.Migration and compatibility notes
Not expected to require migration; one section anchor is removed (update any deep links).
Risks and tradeoffs
Low risk; only consideration is preserving every genuinely distinct comparison row when merging. Keep all neutral.
Suggested labels
documentation, refactor