hnread

# HNRead - Hacker News Discussion Analyzer Fetch a Hacker News discussion thread and extract the most valuable insights from the comments. ## Available Scripts - **`scripts/hn_flat.py`** — Fetches an HN thread and converts it to flat markdown with nested comment structure. By default (`--fetcher auto`) it tries curl, then python-requests, then the Algolia HN API, moving on whenever one fails. ## Workflow 1. **Receive the HN URL** from the user (e.g., `https://news.ycombinator.com/item?id=12345`) 2. **Fetch and convert** the discussion to markdown: ```bash uv run scripts/hn_flat.py "<URL>" --no-frontmatter --stdout ``` If the output is very long (large threads), use condensing to reduce noise: ```bash uv run scripts/hn_flat.py "<URL>" --no-frontmatter --stdout --condense 0.6 ``` 3. **Read the markdown output** and analyze the comments to extract valuable insights. 4. **Present findings** organized into the following categories (skip any category that has no relevant content): ### Output Format Start with the post title and a one-line summary of what the linked article/post is about (infer from comments if needed). Then list insights by category: **Critical Rebuttals / Counterarguments** — Comments that challenge, critique, or offer counterpoints to the article's claims. **Personal Experiences & Anecdotes** — First-hand stories or real-world experiences shared by commenters that add context. **Technical Insights & Corrections** — Technical details, corrections of misconceptions, or deeper explanations. **Notable Debates** — Back-and-forth exchanges between commenters that surface interesting perspectives. **Other Noteworthy Points** — Anything else that stands out as valuable, surprising, or thought-provoking. For each insight: - Write a short summary line describing the point - Quote the relevant comment text (use `>` blockquote), attribute it to the author (`@username`) - If it's a debate, quote both sides Example: ``` **Critical Rebuttals / Counterarguments** 1. The article's claim about X is misleading — the actual situation is Y. > @someuser: "The article completely ignores the fact that..." **Notable Debates** 1. Whether approach A or B is better for large-scale systems. > @user1: "In my experience with distributed systems..." > @user2: "That's true for small clusters, but at scale..." ``` 5. **Language**: Present the analysis in the same language the user used when invoking the skill. If the user wrote in Chinese, respond in Chinese. If in English, respond in English. ## Fetching and Rate Limits - The script handles a refused fetch itself: when HN rejects curl (HTTP 419, 429, 503, or a page that is not the thread), it retries with requests, then falls back to the Algolia API. Don't download the HTML by hand or switch `--fetcher` yourself. - If stderr says the thread came from the Algolia API, keep in mind that replies under each top-level comment are in chronological order, not HN's ranking, and that low-score comments (which the normal path filters out) are included. - If every fetcher fails, do not retry right away. Wait a few minutes, then retry once. - When reading several threads in one task, run the script for one thread at a time, never in parallel, and wait at least 30 seconds between fetches (HN's robots.txt sets `Crawl-delay: 30`), e.g. `sleep 30` between calls. - In batch runs, pass `--cache-dir <dir>` so that rereading a thread you already fetched loads it from disk instead of hitting HN again. ## Notes - Focus on quality over quantity — surface 5-15 truly valuable insights rather than listing everything. - Prefer comments with substance: data, experience, expertise. Skip low-effort reactions. - When a comment thread builds on itself (A replies to B replies to C), capture the full arc if it's insightful. - If the thread is very large, use `--condense 0.5` to reduce noise before analysis.