Reading List Clusterer

What this skill does

Takes a reading list (CSV or markdown) of articles, books, and papers — each with title and optional notes — and clusters them by theme. Within each theme, proposes a reading order that builds concepts incrementally rather than alphabetically.

Inputs

• list_path: CSV or markdown with rows title, url, notes?, tags?.
• Optional top_themes: number of themes to keep (default 5).
• Optional unread_only: boolean default true.

Steps

1. Read entries. For each, fetch its URL and pull the lede (first 500 words) using curl --max-time 10. Cache locally so repeated runs don't re-fetch.
2. Build a TF-IDF vector per item using title + lede + notes.
3. Cluster with hierarchical agglomerative clustering at a chosen distance threshold; pick the cut that yields top_themes clusters with at least 3 items each.
4. Name each theme using the top 5 distinguishing terms.
5. For each theme, score items by "depth": short blog posts that introduce a topic rank earlier; long papers and books rank later. Heuristic: word count + number of citations (look for [N] references in the lede).
6. Build a within-theme order: simpler intro -> intermediate -> advanced. Use a small dependency graph: if item A cites item B explicitly, B must come first.
7. Run a topological sort on the per-theme dependency graph; ties broken by depth score.
8. For cross-theme reading, suggest "start here" prerequisites: the easiest item from each theme.
9. Render a markdown reading plan.
10. Save to reading-plan.md.

Output

reading-plan.md with a "Start here" section, then one section per theme with the ordered list, estimated reading time per item, and notes-to-take prompts. Stdout prints theme count and item count per theme.

Verification

Sample three "depth" assignments by reading the lede; if a paper marked intro is actually advanced, the heuristic is wrong on that domain — surface the override. For the dependency graph, confirm topological order doesn't place a citing paper before its citation. Re-run after marking a few items as "read" and confirm the plan compresses sensibly.

Edge cases

• Items behind paywalls: lede may be a teaser; use available text and tag with paywalled.
• Items in non-text formats (videos): record metadata only; clustering on title is approximate, mark as low-confidence.
• Items with broken URLs: keep title-only entries but place them at the bottom; suggest finding alt sources.
• Reading list of 1-3 items: skip clustering; just sort by depth.