@bompus/house-rules 0.0.0-stage → 0.11.0

package/skills/hr-pr-followup/scripts/resolve-pr-thread.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env bun
+// See ../references/review-helpers.md. One selected thread, dry-run by default, no mutation retries.
+import { parseArgs } from "node:util";
+import { author, date, githubGraphQL, record, text } from "./check-pr-review";
+
+type Selection = { pr: string; thread: string; head: string; reply: string; apply: boolean };
+type Thread = { id: string; isResolved: boolean; isOutdated: boolean; viewerCanResolve: boolean };
+const ACTOR = "{__typename login}";
+const META = `id isResolved isOutdated viewerCanResolve pullRequest{url headRefOid state repository{viewerPermission}}`;
+const COMMENTS = `comments(first:100,after:$cursor){pageInfo{hasNextPage endCursor} nodes{id url body state publishedAt isMinimized author${ACTOR} editor${ACTOR} lastEditedAt replyTo{id}}}`;
+
+function selection(): Selection {
+  const { values, positionals } = parseArgs({
+    options: {
+      thread: { type: "string" },
+      "expect-head": { type: "string" },
+      "reply-url": { type: "string" },
+      apply: { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+  });
+  const [pr] = positionals;
+  if (
+    positionals.length !== 1 ||
+    !pr ||
+    !/^https:\/\/github\.com\/[A-Za-z0-9-]+\/[A-Za-z0-9_.-]+\/pull\/[1-9][0-9]*$/.test(pr) ||
+    !values.thread?.trim() ||
+    !values["expect-head"] ||
+    !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(values["expect-head"]) ||
+    !values["reply-url"]?.startsWith(`${pr}#discussion_r`) ||
+    !/^#discussion_r[1-9][0-9]*$/.test(values["reply-url"].slice(pr.length))
+  ) {
+    throw new Error(
+      "usage: resolve-pr-thread.ts <GitHub PR URL> --thread <id> --expect-head <full SHA> --reply-url <reply URL> [--apply]",
+    );
+  }
+  return {
+    pr,
+    thread: values.thread,
+    head: values["expect-head"],
+    reply: values["reply-url"],
+    apply: values.apply === true,
+  };
+}
+
+function metadata(data: Record<string, unknown>, s: Selection): Thread {
+  const t = record(data.node);
+  const pr = record(t.pullRequest);
+  const permission = record(pr.repository).viewerPermission;
+  if (
+    t.__typename !== "PullRequestReviewThread" ||
+    t.id !== s.thread ||
+    pr.url !== s.pr ||
+    typeof t.isResolved !== "boolean" ||
+    typeof t.isOutdated !== "boolean" ||
+    typeof t.viewerCanResolve !== "boolean" ||
+    !author(data.viewer) ||
+    !(
+      permission === null ||
+      (text(permission) && ["READ", "TRIAGE", "WRITE", "MAINTAIN", "ADMIN"].includes(permission))
+    ) ||
+    !text(pr.state) ||
+    !["OPEN", "CLOSED", "MERGED"].includes(pr.state)
+  ) {
+    throw new Error("malformed or mismatched thread/PR metadata");
+  }
+  if (pr.headRefOid !== s.head) {
+    throw new Error("PR head differs from expected head; stop and re-read");
+  }
+  if (
+    !t.isResolved &&
+    (pr.state !== "OPEN" ||
+      !t.viewerCanResolve ||
+      !["WRITE", "MAINTAIN", "ADMIN"].includes(permission as string))
+  ) {
+    throw new Error("open PR and write/resolve permission required");
+  }
+  return t as unknown as Thread;
+}
+
+function request(s: Selection, comments: boolean, cursor?: string): Record<string, unknown> {
+  const query = `query($thread:ID!${comments ? ",$cursor:String" : ""}){viewer${ACTOR} node(id:$thread){__typename ... on PullRequestReviewThread{${META} ${comments ? COMMENTS : ""}}}}`;
+  return githubGraphQL(query, { thread: s.thread, ...(cursor ? { cursor } : {}) }, "github.com");
+}
+
+function comment(value: unknown): Record<string, unknown> {
+  const c = record(value);
+  if (
+    !text(c.id) ||
+    !text(c.url) ||
+    !text(c.body) ||
+    !text(c.state) ||
+    !["PENDING", "SUBMITTED"].includes(c.state) ||
+    !(c.publishedAt === null || date(c.publishedAt)) ||
+    typeof c.isMinimized !== "boolean" ||
+    !author(c.author) ||
+    !author(c.editor) ||
+    !(c.lastEditedAt === null || date(c.lastEditedAt)) ||
+    !(c.replyTo === null || text(record(c.replyTo).id))
+  ) {
+    throw new Error("malformed thread comment");
+  }
+  return c;
+}
+
+function readSelection(s: Selection): Thread {
+  const seen = new Set<string>();
+  const comments: Record<string, unknown>[] = [];
+  let cursor: string | undefined;
+  let viewer: Record<string, unknown>;
+  for (;;) {
+    const data = request(s, true, cursor);
+    metadata(data, s);
+    viewer = record(data.viewer);
+    const page = record(record(data.node).comments);
+    const info = record(page.pageInfo);
+    if (
+      !Array.isArray(page.nodes) ||
+      typeof info.hasNextPage !== "boolean" ||
+      !(info.endCursor === null || text(info.endCursor))
+    ) {
+      throw new Error("malformed thread comment page");
+    }
+    comments.push(...page.nodes.map(comment));
+    if (!info.hasNextPage) {
+      break;
+    }
+    if (!text(info.endCursor) || !info.endCursor || seen.has(info.endCursor)) {
+      throw new Error("non-advancing thread comment cursor");
+    }
+    seen.add(info.endCursor);
+    cursor = info.endCursor;
+  }
+  const matches = comments.filter((c) => c.url === s.reply);
+  if (matches.length !== 1) {
+    throw new Error("selected reply is missing or ambiguous in this thread");
+  }
+  const reply = matches[0]!;
+  const writer = record(reply.author);
+  const editor = reply.editor === null ? null : record(reply.editor);
+  if (
+    viewer.__typename !== "User" ||
+    writer.__typename !== "User" ||
+    writer.login !== viewer.login ||
+    reply.state !== "SUBMITTED" ||
+    reply.publishedAt === null ||
+    !String(reply.body).trim() ||
+    reply.isMinimized ||
+    reply.replyTo === null ||
+    !comments.some((c) => c.id === record(reply.replyTo).id && c.id !== reply.id) ||
+    (reply.lastEditedAt !== null &&
+      (editor?.__typename !== "User" || editor.login !== viewer.login))
+  ) {
+    throw new Error(
+      "reply must be published, submitted, visible, nonblank, authored by the authenticated human and edited only by that human",
+    );
+  }
+  const final = request(s, false);
+  const currentViewer = record(final.viewer);
+  if (currentViewer.__typename !== viewer.__typename || currentViewer.login !== viewer.login) {
+    throw new Error("authenticated viewer changed during read");
+  }
+  return metadata(final, s);
+}
+
+function resolve(s: Selection): void {
+  const before = readSelection(s);
+  if (before.isResolved) {
+    console.log(`Already resolved: ${s.thread}; no mutation`);
+    return;
+  }
+  if (!s.apply) {
+    console.log(
+      `Dry-run: ready to resolve ${s.thread}${before.isOutdated ? " (outdated)" : ""}; judge the selected reply's explanation before applying`,
+    );
+    return;
+  }
+  let uncertain = false;
+  try {
+    const data = githubGraphQL(
+      "mutation($thread:ID!){resolveReviewThread(input:{threadId:$thread}){thread{id isResolved}}}",
+      { thread: s.thread },
+      "github.com",
+    );
+    const result = record(record(data.resolveReviewThread).thread);
+    if (result.id !== s.thread || result.isResolved !== true) {
+      throw new Error("unverified mutation payload");
+    }
+  } catch {
+    uncertain = true;
+  }
+  // A lost response may hide a successful mutation. Read before any user-initiated retry.
+  let after: Thread;
+  try {
+    after = readSelection(s);
+  } catch (error) {
+    throw new Error(
+      `Mutation attempted once; final verification failed (${error instanceof Error ? error.message : "unknown error"}). Thread may already be resolved; re-read before any retry`,
+      { cause: error },
+    );
+  }
+  if (!after.isResolved) {
+    throw new Error(
+      "thread remains unresolved after mutation attempt; no retry made; re-read before retrying",
+    );
+  }
+  console.log(
+    `Verified resolved: ${s.thread} at ${s.head}${uncertain ? "; mutation response uncertain, fresh state verified" : ""}`,
+  );
+}
+
+if (import.meta.main) {
+  try {
+    resolve(selection());
+  } catch (error) {
+    console.error(`resolve-pr-thread: ${error instanceof Error ? error.message : "failed"}`);
+    process.exitCode = 2;
+  }
+}

package/skills/hr-progress-report/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: hr-progress-report
+description: "Report the current task's activity, completion evidence and remaining wall-clock time. Use for task status, progress, completion percentage or ETA requests. Session-roster and liveness checks belong to the available coordination tools."
+---
+
+# Progress report
+
+Produce a dated snapshot of the requested task. A status request does not
+cancel authorized work or authorize new work. Resume work after the report
+under the governing continuation and offer rules.
+
+1. Identify the task's goal, selected scope and completion criteria. Read
+   the relevant plan and latest results. Name the records checked and any
+   missing coverage. Keep unrelated backlog items outside this task report.
+2. Verify current activity with available job state or recent results.
+   Distinguish working, waiting, blocked and idle. Say when activity cannot
+   be verified; a saved task description alone does not establish current work.
+3. Reconcile completed and remaining milestones against the completion
+   criteria. Include validation and landing when they belong to the selected
+   scope. List blockers and who or what can resolve each one.
+4. State the basis for a completion percentage. Use bounded work units or
+   milestone weights recorded before this report. Label a simple milestone
+   count as milestone completion, not a share of remaining time. During
+   open-ended investigation, report percentage unknown and the evidence gathered.
+   Explain scope changes that alter an earlier percentage. Report full
+   completion only when every selected completion criterion is satisfied.
+5. Show elapsed wall-clock time and remaining ETA under the governing
+   estimate policy. Without one, use comparable finished runs or observed
+   job progress and name the basis. Include tests, CI, review and fix rounds,
+   integration and dependency waits. Give a range and confidence when the
+   evidence supports them. Mark missing evidence or unbounded external waits
+   unknown or unmeasured. Give a running job's finish forecast separately
+   from the whole-task ETA. Include the timezone for clock-time forecasts.
+6. Lead with the task's state and current action, followed by a compact
+   table. Separate verified facts, session estimates and unknowns. End with
+   the next action or required decision using the governing offer format.
+
+| Field                  | Report                                                       |
+| ---------------------- | ------------------------------------------------------------ |
+| Task / state           | Goal, selected scope; working, waiting, blocked or idle      |
+| Current action         | Action and supporting job state or recent result             |
+| Progress               | Completed milestones, percentage basis or unknown            |
+| Remaining              | Unfinished milestones, including checks and integration      |
+| Elapsed / ETA          | Wall-clock time, evidence, confidence and waiting conditions |
+| Blockers / next action | Dependency, owner or decision needed                         |
+
+This is a snapshot, not independent proof of another session's activity.
+Use existing tools and records. Do not start watchers, ping other sessions
+or change schedules merely to produce the report.

package/skills/hr-progress-report/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "HR: Progress report"
+  short_description: "Report task progress and remaining wall-clock time"
+policy:
+  allow_implicit_invocation: true

package/skills/hr-read-reddit/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: hr-read-reddit
+description: Read Reddit threads (post plus comments) and search subreddits in full text, with links kept inline. Use whenever a task needs Reddit content or needs to collect links posted on Reddit; generic web fetch and reddit.com JSON are blocked for agents.
+---
+
+# Read Reddit
+
+Reddit usually answers agent fetches of pages and `.json` with 403, and its
+mirrors are unreliable. Pullpush's archive answers agents with 429 and asks for a
+paid plan, so do not scrape it. The bundled script reads post and comment bodies
+returned by Reddit's public Atom feeds without a key. Feed output can omit
+comments; do not present it as an exhaustive thread.
+
+[Reddit's announcement](https://www.reddit.com/r/modnews/comments/1wubgvt/continuing_our_infrastructure_updates_whats/)
+says RSS support ends November 13, 2026. Until then, try the feeds below and
+report any retrieval failure. After the cutoff, use the partial search fallback
+below rather than assuming the feeds remain supported.
+
+Read feeds with:
+
+```bash
+bun scripts/reddit.ts thread <reddit or redd.it URL>... [--json]
+bun scripts/reddit.ts search <subreddit|all> "<query>" [--pages N] [--since 2026-06-01] [--sort new|relevance|top] [--json]
+```
+
+Run it from this skill's directory. Text output gives each post's title, URL,
+author, date and body, then each comment. Every link appears as
+`text (url)`, so `grep -o` can harvest links. `--json` prints one object per
+entry (`id`, `kind`, `author`, `published`, `title`, `url`, `text`) for scripted
+collection. Search pages hold 100 results. With `--sort new`, `--since` stops
+paging at the first older result.
+
+Limits to state when they matter:
+
+1. Unauthenticated feeds allow about one request per minute. The script waits
+   out Reddit's `x-ratelimit-reset` between requests and retries a 429 twice,
+   so run long searches in the background and keep `--pages` small.
+2. A thread feed is flat: comments come without reply nesting. Images and
+   videos appear only as links.
+3. Search covers what Reddit's own search indexes. A deleted, removed or
+   private thread fails with its HTTP status.
+
+If the feeds are blocked, fall back to the host's web search tool with
+`site:reddit.com`. Say that the results are partial snippets.

package/skills/hr-read-reddit/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "HR: Read Reddit"

package/skills/hr-read-reddit/scripts/reddit.ts

@@ -0,0 +1,252 @@
+#!/usr/bin/env bun
+// Read Reddit threads and subreddit searches through Reddit's public Atom (RSS)
+// feeds: no key, full post and comment bodies, links kept inline.
+import { parseArgs as parseCli } from "node:util";
+
+const ORIGIN = "https://www.reddit.com";
+// Reddit blocks generic agents; its API rules ask for a descriptive user agent.
+const HEADERS = { "user-agent": "linux:agent-read-reddit:v1 (read-only research)" };
+const HOSTS = /^(?:www\.|old\.|new\.|np\.|m\.)?reddit\.com$/;
+
+export type Entry = {
+  id: string;
+  kind: "post" | "comment" | "other";
+  author: string;
+  published: string;
+  title: string;
+  url: string;
+  text: string;
+};
+export type Options = {
+  command: string | undefined;
+  args: string[];
+  json: boolean;
+  pages: number;
+  since: number | null;
+  sort: string;
+};
+
+/** `{ sub, id }` for a thread URL on reddit.com (any subdomain) or redd.it; null otherwise. */
+export function parseThreadUrl(input: string): { sub: string | null; id: string } | null {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+  if (url.hostname === "redd.it") {
+    const id = /^\/([a-z0-9]+)$/i.exec(url.pathname)?.[1];
+    return id ? { sub: null, id } : null;
+  }
+  if (!HOSTS.test(url.hostname)) {
+    return null;
+  }
+  const match = /^\/r\/([^/]+)\/comments\/([a-z0-9]+)/i.exec(url.pathname);
+  return match ? { sub: match[1]!, id: match[2]! } : null;
+}
+
+const ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+};
+export function decodeEntities(s: string): string {
+  return s.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e: string) => {
+    if (e[0] === "#") {
+      return String.fromCodePoint(
+        e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : Number(e.slice(1)),
+      );
+    }
+    return ENTITIES[e.toLowerCase()] ?? m;
+  });
+}
+
+/** Entry HTML as plain text; a link becomes `text (url)`, or the bare URL when the text says nothing. */
+export function htmlToText(html: string): string {
+  const text = html
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<a\s[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, (_, href: string, label: string) => {
+      const url = decodeEntities(href).replace(/^\//, `${ORIGIN}/`);
+      const words = decodeEntities(label.replace(/<[^>]+>/g, "")).trim();
+      return !words || /^\[(link|comments)\]$/.test(words) || words === url
+        ? url
+        : `${words} (${url})`;
+    })
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/(p|div|li|h\d|pre|blockquote|tr)>/gi, "\n")
+    .replace(/<li[^>]*>/gi, "- ")
+    .replace(/<[^>]+>/g, "");
+  return decodeEntities(text)
+    .replace(/[ \t]+/g, " ")
+    .replace(/ *\n */g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/** Atom feed entries: `{ id, kind, author, published, title, url, text }`; kind is post (t3) or comment (t1). */
+export function parseFeed(xml: string): Entry[] {
+  const tag = (s: string, name: string) =>
+    new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`).exec(s)?.[1] ?? "";
+  return [...xml.matchAll(/<entry>([\s\S]*?)<\/entry>/g)].map(([, e = ""]) => {
+    const id = tag(e, "id");
+    return {
+      id,
+      kind: id.startsWith("t3_") ? "post" : id.startsWith("t1_") ? "comment" : ("other" as const),
+      author: tag(tag(e, "author"), "name").replace(/^\/u\//, ""),
+      published: tag(e, "published") || tag(e, "updated"),
+      title: decodeEntities(tag(e, "title")),
+      url: decodeEntities(/<link href="([^"]*)"/.exec(e)?.[1] ?? ""),
+      text: htmlToText(decodeEntities(tag(e, "content"))),
+    };
+  });
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+let waitUntil = 0;
+
+/** GET a feed, spacing requests by Reddit's rate-limit headers and retrying a 429 twice. */
+async function getFeed(url: string): Promise<Entry[]> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const wait = waitUntil - Date.now();
+    if (wait > 0) {
+      console.error(`rate limit: waiting ${Math.ceil(wait / 1000)} s`);
+      await sleep(wait);
+    }
+    const res = await fetch(url, { headers: HEADERS });
+    const reset = Number(res.headers.get("x-ratelimit-reset")) || 60;
+    const remaining = Number(res.headers.get("x-ratelimit-remaining") ?? 1);
+    if (res.status === 429 || remaining < 1) {
+      waitUntil = Date.now() + (reset + 1) * 1000;
+    }
+    if (res.status === 429) {
+      continue;
+    }
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status} for ${url}`);
+    }
+    return parseFeed(await res.text());
+  }
+  throw new Error(`HTTP 429 three times for ${url}`);
+}
+
+const SORTS = ["new", "relevance", "top"];
+
+export function parseArgs(argv: string[]): Options | { error: string } {
+  let parsed;
+  try {
+    parsed = parseCli({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        json: { type: "boolean" },
+        pages: { type: "string" },
+        since: { type: "string" },
+        sort: { type: "string" },
+      },
+    });
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+  const { values, positionals } = parsed;
+  const [command, ...args] = positionals;
+  const pages = Number(values.pages ?? 1);
+  const since = values.since === undefined ? null : Date.parse(values.since);
+  const sort = values.sort ?? "new";
+  if (!Number.isInteger(pages) || pages < 1) {
+    return { error: `bad --pages value ${values.pages}` };
+  }
+  if (Number.isNaN(since)) {
+    return { error: `bad --since value ${values.since}` };
+  }
+  if (!SORTS.includes(sort)) {
+    return { error: `bad --sort value ${sort}` };
+  }
+  const opts: Options = { command, args, json: values.json === true, pages, since, sort };
+  if (command === "thread" && args.length > 0) {
+    return opts;
+  }
+  if (command === "search" && args.length === 2) {
+    return opts;
+  }
+  return { error: command ? `bad arguments for ${command}` : "missing command" };
+}
+
+function print(entry: Entry, json: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(entry));
+    return;
+  }
+  const head = entry.kind === "post" ? `### ${entry.title}\n${entry.url}\n` : "#### comment ";
+  console.log(`${head}u/${entry.author} · ${entry.published}\n\n${entry.text}\n`);
+}
+
+async function main(argv: string[]): Promise<number> {
+  const opts = parseArgs(argv);
+  if ("error" in opts) {
+    console.error(opts.error);
+    console.error("usage: reddit.ts thread <url>... [--json]");
+    console.error(
+      "       reddit.ts search <subreddit|all> <query> [--pages N] [--since ISO-date] [--sort new|relevance|top] [--json]",
+    );
+    return 2;
+  }
+  if (opts.command === "thread") {
+    let failed = 0;
+    for (const input of opts.args) {
+      const ref = parseThreadUrl(input);
+      if (!ref) {
+        console.log(`## ${input}\nnot a Reddit thread URL\n`);
+        failed++;
+        continue;
+      }
+      const path = ref.sub ? `/r/${ref.sub}/comments/${ref.id}` : `/comments/${ref.id}`;
+      try {
+        if (!opts.json) {
+          console.log(`## ${input}`);
+        }
+        for (const entry of await getFeed(`${ORIGIN}${path}/.rss?limit=500`)) {
+          print(entry, opts.json);
+        }
+      } catch (error) {
+        console.log(`fetch failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        failed++;
+      }
+    }
+    return failed ? 1 : 0;
+  }
+  const [sub, query = ""] = opts.args;
+  const base =
+    sub === "all" ? `${ORIGIN}/search.rss?` : `${ORIGIN}/r/${sub}/search.rss?restrict_sr=on&`;
+  let after = "";
+  for (let page = 0; page < opts.pages; page++) {
+    const url = `${base}q=${encodeURIComponent(query)}&sort=${opts.sort}&limit=100${after && `&after=${after}`}`;
+    let entries: Entry[];
+    try {
+      entries = await getFeed(url);
+    } catch (error) {
+      console.log(`fetch failed: ${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+    let old = false;
+    for (const entry of entries) {
+      if (opts.since && Date.parse(entry.published) < opts.since) {
+        old = opts.sort === "new";
+        continue;
+      }
+      print(entry, opts.json);
+    }
+    console.error(`page ${page + 1}: ${entries.length} results`);
+    if (entries.length < 100 || old) {
+      break;
+    }
+    after = entries.at(-1)!.id;
+  }
+  return 0;
+}
+
+if (import.meta.main) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/skills/hr-read-x-links/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: hr-read-x-links
+description: Read X/Twitter post links (x.com, twitter.com and mirrors) in full, including quoted posts, long-form articles, expanded links and attached images. Use whenever a task needs the content of an X post; generic web fetch returns truncated text and no images.
+---
+
+# Read X links
+
+Generic web fetch usually sees X behind a login wall: text cut at "Show more", `t.co`
+links, no images, and quoted articles reduced to a bare link. Read posts through
+the bundled script instead. It calls the public [fxtwitter](https://github.com/FxEmbed/FxEmbed)
+API and needs no key. It sends the post's handle and ID to that third-party
+service and downloads attached images from the URLs it returns.
+
+```bash
+bun scripts/x-post.ts --media-dir <scratch-dir>/media <url> [<url>...]
+```
+
+Run it from this skill's directory. It prints, for each post and any quoted
+post: author, date, full text with expanded links, the article body when the
+post is an X article, and the local path of every downloaded image. Put
+`--media-dir` in your task's scratch directory, on disk rather than in a
+RAM-backed `/tmp`.
+
+Then:
+
+1. Open every downloaded image with the host's image-reading tool. Prompts,
+   tables and charts are often posted only as screenshots.
+2. Follow expanded links (GitHub repos, blog posts) with web fetch when the post
+   only points at the substance.
+3. Report what stayed unread: videos (the script prints the video URL and a
+   thumbnail), earlier posts in a thread (a reply shows its parent's ID; fetch
+   that URL to walk up), and any post the script reported as failed. Say so
+   rather than rating content you did not see.
+4. When the post promotes a tool, method or result, keep what the post claims
+   apart from what its source shows. Check each claim against the repository,
+   docs or paper it links, report what the tool actually does, and name each
+   claim with no evidence behind it, such as a benchmark with no method or a
+   screenshot with no source.
+
+A deleted, protected or age-restricted post fails with the API's message; ask
+the user for a screenshot. If the API itself is down, fall back to web fetch
+and state that text and images may be incomplete.

package/skills/hr-read-x-links/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "HR: Read X links"