betatim · October 27, 2026 12:59
diff --git a/reference.md b/reference.md
diff --git a/scripts_slash_fetch_open_prs.py b/scripts_slash_fetch_open_prs.py
 #!/usr/bin/env python3
 """Fetch every open PR of a repository into a local JSON cache via the GitHub GraphQL API.

 Only bulk metadata is fetched here: enough to apply the worklist filter without
 touching the REST search API, which is capped at 30 requests/minute. Per-PR
 detail (body, diff, discussion) is the job of pr_context.py.

 Page size is deliberately 25. Larger pages combined with the nested `files` and
 `comments` selections exceed GitHub's node limit, and the failure mode is an
 empty response body rather than an error, so it is easy to mistake for success.
 """

 from __future__ import annotations

 import argparse
 import datetime as dt
 import json
 import pathlib
 import subprocess
 import sys
 import time

 DEFAULT_REPO = "scikit-learn/scikit-learn"
 PAGE_SIZE = 25

 QUERY = """
 query($owner: String!, $name: String!, $size: Int!, $cursor: String) {
  rateLimit { cost remaining resetAt }
  repository(owner: $owner, name: $name) {
    pullRequests(states: OPEN, first: $size, after: $cursor) {
      totalCount
      pageInfo { hasNextPage endCursor }
      nodes {
        number title url createdAt updatedAt isDraft
        additions deletions changedFiles
        author { login }
        authorAssociation
        labels(first: 20) { nodes { name } }
        comments(last: 40) { totalCount nodes { authorAssociation } }
        reviews(last: 40) { totalCount nodes { authorAssociation state } }
        files(first: 60) { totalCount nodes { path } }
        closingIssuesReferences(first: 5) { nodes { number title url } }
      }
    }
  }
 }
 """


 class FetchError(RuntimeError):
    pass


 def run_graphql(owner: str, name: str, cursor: str | None, size: int) -> dict:
    """Execute one GraphQL page, with retries for transient and node-limit failures."""
    args = [
        "gh", "api", "graphql",
        "-f", f"query={QUERY}",
        "-F", f"owner={owner}",
        "-F", f"name={name}",
        "-F", f"size={size}",
    ]
    if cursor:
        args += ["-F", f"cursor={cursor}"]

    last_problem = "unknown"
    for attempt in range(4):
        proc = subprocess.run(args, capture_output=True, text=True)

        # An empty body is the signature of exceeding the node limit. It is not
        # reported as an error, so it must be checked explicitly.
        if not proc.stdout.strip():
            last_problem = f"empty response body (exit {proc.returncode}): {proc.stderr.strip()[:300]}"
        else:
            try:
                payload = json.loads(proc.stdout)
            except json.JSONDecodeError as exc:
                last_problem = f"unparseable response: {exc}"
            else:
                if "errors" in payload:
                    last_problem = "GraphQL errors: " + json.dumps(payload["errors"])[:300]
                elif not payload.get("data", {}).get("repository"):
                    last_problem = "response contained no repository data"
                else:
                    return payload

        if attempt < 3:
            time.sleep(2 * (attempt + 1))

    raise FetchError(last_problem)


 def fetch_all(owner: str, name: str, size: int, quiet: bool) -> tuple[list[dict], dict]:
    nodes: list[dict] = []
    cursor: str | None = None
    cost = 0
    rate: dict = {}

    while True:
        payload = run_graphql(owner, name, cursor, size)
        rate = payload["data"]["rateLimit"]
        cost += rate["cost"]
        page = payload["data"]["repository"]["pullRequests"]
        nodes += page["nodes"]

        if not quiet:
            print(
                f"  fetched {len(nodes)}/{page['totalCount']} open PRs",
                file=sys.stderr,
            )
        if not page["pageInfo"]["hasNextPage"]:
            break
        cursor = page["pageInfo"]["endCursor"]

    return nodes, {"cost": cost, "remaining": rate.get("remaining")}


 def cache_age_hours(path: pathlib.Path) -> float | None:
    """Age of the cache in hours, or None if it is absent or unreadable."""
    if not path.exists():
        return None
    try:
        stamp = json.loads(path.read_text())["fetched_at"]
        fetched = dt.datetime.fromisoformat(stamp)
    except (json.JSONDecodeError, KeyError, ValueError, OSError):
        return None
    if fetched.tzinfo is None:
        fetched = fetched.replace(tzinfo=dt.timezone.utc)
    delta = dt.datetime.now(dt.timezone.utc) - fetched
    return delta.total_seconds() / 3600.0


 def default_cache_path(repo: str) -> pathlib.Path:
    slug = repo.replace("/", "-")
    return pathlib.Path("agents/impact/.cache") / f"open-prs-{slug}.json"


 def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--repo", default=DEFAULT_REPO, help=f"owner/name (default {DEFAULT_REPO})")
    parser.add_argument("--cache", type=pathlib.Path, help="cache file path")
    parser.add_argument(
        "--max-age-hours",
        type=float,
        default=24.0,
        help="reuse the cache if it is younger than this (default 24)",
    )
    parser.add_argument("--force", action="store_true", help="refetch regardless of cache age")
    parser.add_argument("--quiet", action="store_true", help="suppress progress output")
    args = parser.parse_args()

    if "/" not in args.repo:
        print(f"error: --repo must be owner/name, got {args.repo!r}", file=sys.stderr)
        return 2
    owner, name = args.repo.split("/", 1)

    cache = args.cache or default_cache_path(args.repo)
    age = cache_age_hours(cache)

    if not args.force and age is not None and age < args.max_age_hours:
        data = json.loads(cache.read_text())
        print(f"cache fresh ({age:.1f}h old): {data['count']} open PRs at {cache}")
        return 0

    if not args.quiet:
        reason = "no usable cache" if age is None else f"cache {age:.1f}h old"
        print(f"fetching {args.repo} ({reason})...", file=sys.stderr)

    try:
        nodes, usage = fetch_all(owner, name, PAGE_SIZE, args.quiet)
    except FetchError as exc:
        print(f"error: fetch failed: {exc}", file=sys.stderr)
        return 1

    cache.parent.mkdir(parents=True, exist_ok=True)
    cache.write_text(
        json.dumps(
            {
                "fetched_at": dt.datetime.now(dt.timezone.utc).isoformat(),
                "repo": args.repo,
                "count": len(nodes),
                "prs": nodes,
            },
            indent=1,
        )
    )

    truncated = [n["number"] for n in nodes if n["files"]["totalCount"] > 60]
    print(f"wrote {len(nodes)} open PRs to {cache} (rate-limit cost {usage['cost']}, {usage['remaining']} remaining)")
    if truncated:
        print(f"note: file lists truncated at 60 for PRs {truncated}")
    return 0


 if __name__ == "__main__":
    sys.exit(main())
diff --git a/scripts_slash_filter_prs.py b/scripts_slash_filter_prs.py
 #!/usr/bin/env python3
 """Apply the worklist filter to the open-PR cache and draw the next PR to brief.

 The default worklist is PRs that touch scikit-learn source and that no core
 developer has ever commented on or reviewed. Those are the PRs where the
 question "should we carry this?" has demonstrably never been asked.

 Core-dev engagement is detected via `authorAssociation` of MEMBER or OWNER on
 any comment or review. PRs authored by a core dev are deliberately kept when no
 *other* core dev has engaged: an unattended core-dev PR carries the same
 unanswered question.
 """

 from __future__ import annotations

 import argparse
 import json
 import pathlib
 import random
 import re
 import sys

 CORE_ASSOCIATIONS = {"MEMBER", "OWNER"}
 FEATURE_TITLE = re.compile(r"^\s*(ENH|FEA|API|PRF)\b", re.IGNORECASE)
 FEATURE_LABELS = {"New Feature", "Enhancement", "API"}
 DOC_SUFFIXES = (".rst", ".md", ".txt")
 # Leading commit-tag conventions stripped when building a filename slug.
 TITLE_TAG = re.compile(
    r"^\s*(ENH|FEA|FIX|DOC|MAINT|CI|TST|BLD|PRF|API|RFC|CLN|BUG|POC|WIP)[:\s]+",
    re.IGNORECASE,
 )


 def is_bot(pr: dict) -> bool:
    login = (pr.get("author") or {}).get("login") or ""
    return login.endswith("[bot]") or login in {"scikit-learn-bot", "dependabot"}


 def core_engaged(pr: dict) -> bool:
    for comment in pr["comments"]["nodes"]:
        if comment["authorAssociation"] in CORE_ASSOCIATIONS:
            return True
    for review in pr["reviews"]["nodes"]:
        if review["authorAssociation"] in CORE_ASSOCIATIONS:
            return True
    return False


 def core_approved(pr: dict) -> bool:
    return any(
        r["state"] == "APPROVED" and r["authorAssociation"] in CORE_ASSOCIATIONS
        for r in pr["reviews"]["nodes"]
    )


 def touches_sklearn_source(pr: dict) -> bool:
    for f in pr["files"]["nodes"]:
        path = f["path"]
        if not path.startswith("sklearn/"):
            continue
        if "/tests/" in path or path.startswith("sklearn/tests/"):
            continue
        if path.endswith((".py", ".pyx", ".pxd", ".pyx.tp")):
            return True
    return False


 def docs_only(pr: dict) -> bool:
    paths = [f["path"] for f in pr["files"]["nodes"]]
    if not paths:
        return False
    return all(
        p.startswith(("doc/", "examples/")) or p.endswith(DOC_SUFFIXES) for p in paths
    )


 def featurey(pr: dict) -> bool:
    labels = {node["name"] for node in pr["labels"]["nodes"]}
    return bool(FEATURE_TITLE.match(pr["title"]) or (labels & FEATURE_LABELS))


 def slug_for(pr: dict, words: int = 7) -> str:
    """Deterministic filename slug, so the same PR always maps to the same file."""
    title = TITLE_TAG.sub("", pr["title"])
    cleaned = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
    parts = [part for part in cleaned.split("-") if part]
    return "-".join(parts[:words]) or "untitled"


 def modules_of(pr: dict) -> list[str]:
    return sorted(
        node["name"].removeprefix("module:")
        for node in pr["labels"]["nodes"]
        if node["name"].startswith("module:")
    )


 def build_worklist(prs: list[dict], mode: str) -> list[dict]:
    candidates = [p for p in prs if not p["isDraft"] and not is_bot(p)]
    if mode == "all":
        return candidates
    selected = [
        p
        for p in candidates
        if not core_engaged(p)
        and touches_sklearn_source(p)
        and not docs_only(p)
        and not core_approved(p)
    ]
    if mode == "featurey":
        selected = [p for p in selected if featurey(p)]
    return selected


 def already_briefed(brief_dir: pathlib.Path) -> set[int]:
    """PR numbers that already have a brief. Existence of the file is the state.

    Recursive, so filing a brief under `done/` still counts as briefed. Without
    that, archiving a brief would put its PR back in the draw.
    """
    numbers: set[int] = set()
    if not brief_dir.exists():
        return numbers
    for path in brief_dir.rglob("*.md"):
        head = path.stem.split("-", 1)[0]
        if head.isdigit():
            numbers.add(int(head))
    return numbers


 def print_table(rows: list[dict], briefed: set[int]) -> None:
    for pr in rows:
        mark = "*" if pr["number"] in briefed else " "
        mods = ",".join(modules_of(pr)) or "-"
        print(
            f"{mark}#{pr['number']:<6} {pr['createdAt'][:7]}  "
            f"+{pr['additions']:<5}/-{pr['deletions']:<5} "
            f"{pr['authorAssociation'][:22]:<22} {mods[:24]:<24} {pr['title'][:70]}"
        )


 def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--cache", type=pathlib.Path, help="open-PR cache path")
    parser.add_argument("--repo", default="scikit-learn/scikit-learn")
    group = parser.add_mutually_exclusive_group()
    group.add_argument(
        "--featurey",
        action="store_const",
        const="featurey",
        dest="mode",
        help="narrow to public-surface additions only",
    )
    group.add_argument(
        "--all",
        action="store_const",
        const="all",
        dest="mode",
        help="widen to every human non-draft PR",
    )
    parser.add_argument(
        "--brief-dir",
        type=pathlib.Path,
        default=pathlib.Path("agents/impact"),
        help="directory of existing briefs (default agents/impact)",
    )
    parser.add_argument("--pick", type=int, metavar="N", help="draw N unbriefed PRs at random")
    parser.add_argument("--seed", type=int, help="seed the random draw for reproducibility")
    parser.add_argument("--include-briefed", action="store_true", help="do not skip briefed PRs")
    parser.add_argument("--json", action="store_true", help="emit JSON instead of a table")
    parser.add_argument("--counts", action="store_true", help="print filter cardinalities and exit")
    parser.set_defaults(mode="default")
    args = parser.parse_args()

    cache = args.cache or pathlib.Path("agents/impact/.cache") / f"open-prs-{args.repo.replace('/', '-')}.json"
    if not cache.exists():
        print(f"error: no cache at {cache}; run fetch_open_prs.py first", file=sys.stderr)
        return 1
    data = json.loads(cache.read_text())
    prs = data["prs"]

    if args.counts:
        print(f"cache fetched {data['fetched_at']}  repo {data['repo']}")
        print(f"{'total open':46s} {len(prs)}")
        print(f"{'  drafts':46s} {sum(1 for p in prs if p['isDraft'])}")
        print(f"{'  bot-authored':46s} {sum(1 for p in prs if is_bot(p))}")
        for label, mode in [
            ("--all (human, non-draft)", "all"),
            ("default (unengaged + touches sklearn)", "default"),
            ("--featurey", "featurey"),
        ]:
            print(f"{label:46s} {len(build_worklist(prs, mode))}")
        return 0

    worklist = build_worklist(prs, args.mode)
    worklist.sort(key=lambda p: p["createdAt"])
    briefed = already_briefed(args.brief_dir)

    pool = worklist if args.include_briefed else [p for p in worklist if p["number"] not in briefed]

    if args.pick is not None:
        if not pool:
            print(
                f"worklist exhausted: all {len(worklist)} PRs in mode '{args.mode}' already have briefs "
                f"in {args.brief_dir}",
                file=sys.stderr,
            )
            return 3
        rng = random.Random(args.seed)
        pool = rng.sample(pool, min(args.pick, len(pool)))

    if args.json:
        print(
            json.dumps(
                [
                    {
                        "number": p["number"],
                        "title": p["title"],
                        "url": p["url"],
                        "slug": slug_for(p),
                        "brief_path": str(args.brief_dir / f"{p['number']}-{slug_for(p)}.md"),
                        "created_at": p["createdAt"],
                        "updated_at": p["updatedAt"],
                        "author": (p.get("author") or {}).get("login"),
                        "author_association": p["authorAssociation"],
                        "additions": p["additions"],
                        "deletions": p["deletions"],
                        "changed_files": p["changedFiles"],
                        "labels": [n["name"] for n in p["labels"]["nodes"]],
                        "modules": modules_of(p),
                        "featurey": featurey(p),
                        "comment_count": p["comments"]["totalCount"],
                        "review_count": p["reviews"]["totalCount"],
                        "linked_issues": [
                            {"number": c["number"], "title": c["title"], "url": c["url"]}
                            for c in p["closingIssuesReferences"]["nodes"]
                        ],
                        "already_briefed": p["number"] in briefed,
                    }
                    for p in pool
                ],
                indent=1,
            )
        )
        return 0

    print_table(pool, briefed)
    suffix = "" if args.include_briefed else f", {len(briefed & {p['number'] for p in worklist})} already briefed and skipped"
    print(f"\n{len(pool)} PRs shown (mode '{args.mode}', worklist {len(worklist)}{suffix})")
    return 0


 if __name__ == "__main__":
    sys.exit(main())
diff --git a/scripts_slash_pr_context.py b/scripts_slash_pr_context.py
 #!/usr/bin/env python3
 """Assemble the deterministic context bundle for one PR.

 Everything here is mechanical and sourced. The judgment that this bundle feeds
 -- reach, counterfactual availability, cost, and the questions the decision
 hinges on -- is the model's job, not this script's.

 Four things are gathered:

 1. PR metadata, body, and the diff.
 2. Linked issues with their discussion, which is usually where the only
   statement of user impact lives.
 3. The public API surface delta, computed by parsing the base and head versions
   of each changed Python file with `ast` and comparing them. Path heuristics do
   not work for scikit-learn, whose public names live in privately-named files
   such as `_classification.py`, so the surface is derived from the code itself.
 4. Prior art: earlier issues and PRs proposing the same thing, plus other open
   PRs touching the same files. The latter comes from the local cache at zero
   API cost and is how overlapping PRs get noticed.
 """

 from __future__ import annotations

 import argparse
 import ast
 import base64
 import json
 import pathlib
 import re
 import subprocess
 import sys
 import time

 DEFAULT_REPO = "scikit-learn/scikit-learn"
 # The REST search API allows 30 requests/minute. Stay well under it.
 SEARCH_SLEEP_S = 2.5
 MAX_SEARCH_QUERIES = 5
 MAX_SURFACE_FILES = 12
 MAX_LINKED_ISSUES = 6

 PR_QUERY = """
 query($owner: String!, $name: String!, $number: Int!) {
  repository(owner: $owner, name: $name) {
    pullRequest(number: $number) {
      number title url body state isDraft createdAt updatedAt
      additions deletions changedFiles
      author { login }
      authorAssociation
      baseRefName headRefName baseRefOid headRefOid
      isCrossRepository
      headRepository { nameWithOwner }
      labels(first: 25) { nodes { name } }
      files(first: 100) { totalCount nodes { path additions deletions } }
      comments(first: 60) {
        totalCount
        nodes { author { login } authorAssociation createdAt body }
      }
      reviews(first: 40) {
        totalCount
        nodes { author { login } authorAssociation state submittedAt body }
      }
      closingIssuesReferences(first: 10) { nodes { number } }
    }
  }
 }
 """

 ISSUE_QUERY = """
 query($owner: String!, $name: String!, $number: Int!) {
  repository(owner: $owner, name: $name) {
    issue(number: $number) {
      number title url state stateReason createdAt closedAt body
      author { login }
      reactions { totalCount }
      labels(first: 25) { nodes { name } }
      comments(first: 40) {
        totalCount
        nodes { author { login } authorAssociation createdAt body }
      }
    }
  }
 }
 """

 STOPWORDS = {
    "add", "adds", "added", "adding", "allow", "allows", "and", "any", "are", "avoid",
    "based", "better", "between", "bug", "but", "can", "case", "cases", "change",
    "changes", "check", "class", "common", "correct", "data", "default", "deprecate",
    "doc", "docs", "does", "dont", "during", "else", "ensure", "error", "example",
    "examples", "fail", "failing", "fails", "fix", "fixed", "fixes", "for", "from",
    "function", "handle", "handling", "has", "have", "improve", "improved", "input",
    "instead", "into", "issue", "make", "makes", "method", "methods", "missing",
    "more", "new", "not", "now", "only", "option", "parameter", "parameters", "pass",
    "raise", "raises", "remove", "removed", "return", "returns", "same", "set",
    "should", "small", "some", "support", "test", "tests", "that", "the", "their",
    "then", "there", "this", "throw", "use", "used", "using", "value", "values",
    "when", "where", "which", "with", "without", "wrong",
 }


 # --------------------------------------------------------------------------- gh


 def gh(args: list[str]) -> str:
    proc = subprocess.run(args, capture_output=True, text=True)
    if proc.returncode != 0 or not proc.stdout.strip():
        raise RuntimeError(f"{' '.join(args[:3])} failed: {proc.stderr.strip()[:300]}")
    return proc.stdout


 def graphql(query: str, **variables) -> dict:
    args = ["gh", "api", "graphql", "-f", f"query={query}"]
    for key, value in variables.items():
        args += ["-F", f"{key}={value}"]
    payload = json.loads(gh(args))
    if "errors" in payload:
        raise RuntimeError("GraphQL errors: " + json.dumps(payload["errors"])[:300])
    return payload["data"]


 def fetch_blob(repo: str, path: str, ref: str) -> str | None:
    """File contents at a ref. Works for fork head SHAs via the base repo."""
    try:
        raw = gh(["gh", "api", f"repos/{repo}/contents/{path}?ref={ref}"])
    except RuntimeError:
        return None
    try:
        node = json.loads(raw)
        if node.get("encoding") != "base64":
            return None
        return base64.b64decode(node["content"]).decode("utf-8", errors="replace")
    except (json.JSONDecodeError, KeyError, ValueError):
        return None


 # ----------------------------------------------------------- public API surface


 def _params(node: ast.FunctionDef | ast.AsyncFunctionDef) -> dict[str, str]:
    """Parameter name -> rendered default ('' when the parameter is required)."""
    out: dict[str, str] = {}
    pos = list(node.args.posonlyargs) + list(node.args.args)
    defaults = list(node.args.defaults)
    pad = len(pos) - len(defaults)
    for index, arg in enumerate(pos):
        if arg.arg == "self":
            continue
        default = defaults[index - pad] if index >= pad else None
        out[arg.arg] = _render(default)
    if node.args.vararg:
        out["*" + node.args.vararg.arg] = ""
    for arg, default in zip(node.args.kwonlyargs, node.args.kw_defaults):
        out[arg.arg] = _render(default)
    if node.args.kwarg:
        out["**" + node.args.kwarg.arg] = ""
    return out


 def _render(node: ast.AST | None) -> str:
    if node is None:
        return ""
    try:
        return ast.unparse(node)
    except Exception:
        return "?"


 def public_surface(source: str) -> dict:
    """Public functions, classes and methods with their parameters.

    `__init__` is treated as public because for a scikit-learn estimator its
    parameters *are* the public API.
    """
    try:
        tree = ast.parse(source)
    except SyntaxError:
        return {}
    surface: dict[str, dict[str, str]] = {}
    for node in tree.body:
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            if not node.name.startswith("_"):
                surface[node.name] = _params(node)
        elif isinstance(node, ast.ClassDef) and not node.name.startswith("_"):
            surface[node.name + " (class)"] = {}
            for item in node.body:
                if not isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
                    continue
                if item.name.startswith("_") and item.name != "__init__":
                    continue
                surface[f"{node.name}.{item.name}"] = _params(item)
    return surface


 def surface_delta(base_src: str | None, head_src: str | None) -> dict:
    """Added/removed callables, and added/removed/retyped parameters."""
    base = public_surface(base_src) if base_src else {}
    head = public_surface(head_src) if head_src else {}
    delta: dict[str, list] = {
        "added_callables": sorted(set(head) - set(base)),
        "removed_callables": sorted(set(base) - set(head)),
        "added_params": [],
        "removed_params": [],
        "changed_defaults": [],
    }
    for name in sorted(set(base) & set(head)):
        before, after = base[name], head[name]
        for param in sorted(set(after) - set(before)):
            default = after[param]
            delta["added_params"].append(
                f"{name}({param}{'=' + default if default else ''})"
            )
        for param in sorted(set(before) - set(after)):
            delta["removed_params"].append(f"{name}({param})")
        for param in sorted(set(before) & set(after)):
            if before[param] != after[param]:
                delta["changed_defaults"].append(
                    f"{name}({param}): {before[param] or '<required>'} -> {after[param] or '<required>'}"
                )
    return delta


 # ------------------------------------------------------------------ prior art


 def search_terms(title: str, surface: dict) -> list[str]:
    """Distinctive identifiers worth searching history for."""
    terms: list[str] = []
    for match in re.findall(r"`([^`]+)`", title):
        terms.append(match.strip())
    for match in re.findall(r"\b([A-Z][a-zA-Z0-9]*[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*)\b", title):
        terms.append(match)
    for entry in surface.get("added_params", []):
        name = re.search(r"\(([^=)]+)", entry)
        if name:
            terms.append(name.group(1))
    for entry in surface.get("added_callables", []):
        terms.append(entry.replace(" (class)", "").split(".")[-1])
    for word in re.findall(r"\b[a-z][a-z_]{4,}\b", title.lower()):
        if word not in STOPWORDS:
            terms.append(word)

    seen: list[str] = []
    for term in terms:
        term = term.strip().strip("`'\"")
        if len(term) < 4 or term.lower() in STOPWORDS:
            continue
        if term.lower() not in {t.lower() for t in seen}:
            seen.append(term)
    return seen[:MAX_SEARCH_QUERIES]


 def is_identifier_like(term: str) -> bool:
    """Code identifiers are high-precision search terms; bare English words are not."""
    return "_" in term or any(c.isupper() for c in term)


 def prior_art(repo: str, number: int, terms: list[str]) -> tuple[list[dict], list[str]]:
    """Earlier issues and PRs mentioning the same identifiers.

    Broad single-word terms are capped hard. Searching scikit-learn history for
    a word like "categorical" returns dozens of unrelated hits that bury the one
    result that matters, which is usually a previous attempt at the same change.
    """
    hits: dict[int, dict] = {}
    notes: list[str] = []
    # Search the precise terms first, so the per-term budget is spent well.
    ordered = sorted(terms, key=lambda t: not is_identifier_like(t))
    for index, term in enumerate(ordered):
        if index:
            time.sleep(SEARCH_SLEEP_S)
        broad = not is_identifier_like(term)
        cap = 4 if broad else 25
        query = f'repo:{repo} "{term}" in:title'
        try:
            raw = gh([
                "gh", "api", "-X", "GET", "search/issues",
                "-f", f"q={query}", "-f", "per_page=30",
                "-f", "sort=created", "-f", "order=desc",
            ])
        except RuntimeError as exc:
            notes.append(f"search for {term!r} failed ({str(exc)[:80]}) -- prior art may be incomplete")
            continue
        try:
            payload = json.loads(raw)
            items = payload.get("items", [])
        except json.JSONDecodeError:
            notes.append(f"search for {term!r} returned unparseable JSON")
            continue
        if broad and payload.get("total_count", 0) > cap:
            notes.append(
                f"{term!r} is a broad term with {payload['total_count']} title matches; "
                f"showing the {cap} most recent only"
            )
        for item in items[:cap]:
            if item["number"] == number:
                continue
            hits.setdefault(item["number"], {
                "number": item["number"],
                "title": item["title"],
                "url": item["html_url"],
                "kind": "pr" if "pull_request" in item else "issue",
                "state": item["state"],
                "merged": bool(item.get("pull_request", {}).get("merged_at")),
                "created_at": item["created_at"][:10],
                "closed_at": (item.get("closed_at") or "")[:10],
                "matched": term,
            })
    return sorted(hits.values(), key=lambda h: h["created_at"]), notes


 def overlapping_open_prs(cache: pathlib.Path, number: int, paths: set[str]) -> list[dict]:
    """Other open PRs touching the same files. Read from the cache, no API cost."""
    if not cache.exists():
        return []
    try:
        prs = json.loads(cache.read_text())["prs"]
    except (json.JSONDecodeError, KeyError, OSError):
        return []
    out = []
    for pr in prs:
        if pr["number"] == number:
            continue
        shared = paths & {f["path"] for f in pr["files"]["nodes"]}
        if shared:
            out.append({
                "number": pr["number"],
                "title": pr["title"],
                "url": pr["url"],
                "created_at": pr["createdAt"][:10],
                "is_draft": pr["isDraft"],
                "shared_files": sorted(shared),
            })
    return sorted(out, key=lambda p: -len(p["shared_files"]))


 # --------------------------------------------------------------------- render


 def truncate(text: str | None, limit: int) -> str:
    text = (text or "").strip()
    if len(text) <= limit:
        return text or "(empty)"
    return text[:limit] + f"\n... [truncated, {len(text) - limit} more characters]"


 def render(bundle: dict, diff_lines: int) -> str:
    pr = bundle["pr"]
    out: list[str] = []
    add = out.append

    add(f"# Context bundle: PR #{pr['number']} -- {pr['title']}")
    add("")
    add(f"- URL: {pr['url']}")
    add(f"- Author: {(pr.get('author') or {}).get('login')} ({pr['authorAssociation']})")
    add(f"- Opened {pr['createdAt'][:10]}, last updated {pr['updatedAt'][:10]}")
    add(f"- Size: +{pr['additions']}/-{pr['deletions']} across {pr['changedFiles']} files")
    add(f"- Labels: {', '.join(n['name'] for n in pr['labels']['nodes']) or 'none'}")
    add(f"- Base {pr['baseRefName']} @ {pr['baseRefOid'][:9]}, head {pr['headRefName']} @ {pr['headRefOid'][:9]}")
    add(f"- Comments: {pr['comments']['totalCount']}, reviews: {pr['reviews']['totalCount']}")
    add("")

    add("## PR body")
    add("")
    add(truncate(pr["body"], 4000))
    add("")

    add("## Changed files")
    add("")
    for f in pr["files"]["nodes"]:
        add(f"- `{f['path']}` +{f['additions']}/-{f['deletions']}")
    if pr["files"]["totalCount"] > len(pr["files"]["nodes"]):
        add(f"- ... {pr['files']['totalCount'] - len(pr['files']['nodes'])} more files")
    add("")

    add("## Public API surface delta")
    add("")
    add("Computed by parsing base and head with `ast`. Empty means this PR adds no public surface.")
    add("")
    add("Caveat: this is a per-file, per-class view and does not follow inheritance. A method "
        "moved to a new base class shows up as both removed and added, which is a refactor "
        "rather than a removal of public API. Check the diff before describing anything as removed.")
    add("")
    surface = bundle["surface"]
    if not any(surface.get(k) for k in ("added_callables", "removed_callables", "added_params", "removed_params", "changed_defaults")):
        add("No public API surface change detected.")
    else:
        for key, label in [
            ("added_callables", "New public callables"),
            ("removed_callables", "Removed public callables"),
            ("added_params", "New parameters"),
            ("removed_params", "Removed parameters"),
            ("changed_defaults", "Changed defaults (behaviour change for existing users)"),
        ]:
            if surface.get(key):
                add(f"**{label}:**")
                for entry in surface[key]:
                    add(f"- `{entry}`")
                add("")
    for note in bundle["surface_notes"]:
        add(f"- note: {note}")
    add("")

    add("## Linked issues")
    add("")
    if not bundle["issues"]:
        add("No linked issue. The PR body is the only statement of motivation.")
    for issue in bundle["issues"]:
        state = issue["state"] + (f"/{issue['stateReason']}" if issue.get("stateReason") else "")
        add(f"### #{issue['number']} {issue['title']} [{state}]")
        add("")
        add(f"{issue['url']} -- opened {issue['createdAt'][:10]} by "
            f"{(issue.get('author') or {}).get('login')}, "
            f"{issue['reactions']['totalCount']} reactions, "
            f"{issue['comments']['totalCount']} comments")
        add(f"Labels: {', '.join(n['name'] for n in issue['labels']['nodes']) or 'none'}")
        add("")
        add(truncate(issue["body"], 2500))
        add("")
        if issue["comments"]["nodes"]:
            add("Discussion:")
            add("")
            for comment in issue["comments"]["nodes"]:
                who = (comment.get("author") or {}).get("login")
                add(f"- **{who}** ({comment['authorAssociation']}, {comment['createdAt'][:10]}): "
                    f"{truncate(comment['body'], 700)}")
            add("")

    add("## PR discussion")
    add("")
    if not pr["comments"]["nodes"] and not pr["reviews"]["nodes"]:
        add("None. Nobody has said anything on this PR.")
    for comment in pr["comments"]["nodes"]:
        who = (comment.get("author") or {}).get("login")
        add(f"- **{who}** ({comment['authorAssociation']}, {comment['createdAt'][:10]}): "
            f"{truncate(comment['body'], 700)}")
    for review in pr["reviews"]["nodes"]:
        who = (review.get("author") or {}).get("login")
        add(f"- **{who}** review {review['state']} ({review['authorAssociation']}, "
            f"{(review.get('submittedAt') or '')[:10]}): {truncate(review['body'], 700)}")
    add("")

    add("## Prior art: history mentioning the same identifiers")
    add("")
    add(f"Search terms: {', '.join(bundle['terms']) or 'none derived'}")
    add("")
    if not bundle["prior_art"]:
        add("No earlier issues or PRs found for these terms.")
    for hit in bundle["prior_art"]:
        status = "merged" if hit["merged"] else hit["state"]
        closed = f", closed {hit['closed_at']}" if hit["closed_at"] else ""
        add(f"- [{hit['kind']} #{hit['number']}]({hit['url']}) [{status}] "
            f"created {hit['created_at']}{closed} -- {hit['title']} (matched `{hit['matched']}`)")
    for note in bundle["prior_art_notes"]:
        add(f"- note: {note}")
    add("")

    add("## Other open PRs touching the same files")
    add("")
    if not bundle["overlaps"]:
        add("None.")
    for overlap in bundle["overlaps"]:
        draft = " (draft)" if overlap["is_draft"] else ""
        add(f"- [#{overlap['number']}]({overlap['url']}){draft} opened {overlap['created_at']} -- "
            f"{overlap['title']} -- shares {', '.join('`' + p + '`' for p in overlap['shared_files'])}")
    add("")

    add("## Diff")
    add("")
    diff = bundle["diff"].splitlines()
    if len(diff) > diff_lines:
        add(f"Truncated to the first {diff_lines} of {len(diff)} lines.")
        add("")
        diff = diff[:diff_lines]
    add("```diff")
    out.extend(diff)
    add("```")
    return "\n".join(out)


 # ----------------------------------------------------------------------- main


 def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("number", type=int, help="PR number")
    parser.add_argument("--repo", default=DEFAULT_REPO)
    parser.add_argument("--out", type=pathlib.Path, help="write to this path instead of stdout")
    parser.add_argument("--json", action="store_true", help="emit the raw bundle as JSON")
    parser.add_argument("--diff-lines", type=int, default=2000, help="cap on diff lines (default 2000)")
    parser.add_argument("--no-prior-art", action="store_true", help="skip the throttled history search")
    parser.add_argument("--cache", type=pathlib.Path, help="open-PR cache, for overlap detection")
    args = parser.parse_args()

    owner, name = args.repo.split("/", 1)
    try:
        pr = graphql(PR_QUERY, owner=owner, name=name, number=args.number)["repository"]["pullRequest"]
    except RuntimeError as exc:
        print(f"error: could not fetch PR #{args.number}: {exc}", file=sys.stderr)
        return 1
    if pr is None:
        print(f"error: PR #{args.number} not found in {args.repo}", file=sys.stderr)
        return 1

    try:
        diff = gh(["gh", "pr", "diff", str(args.number), "--repo", args.repo])
    except RuntimeError as exc:
        diff = f"(diff unavailable: {exc})"

    # Public API surface delta, per changed Python file.
    surface: dict[str, list] = {
        "added_callables": [], "removed_callables": [],
        "added_params": [], "removed_params": [], "changed_defaults": [],
    }
    surface_notes: list[str] = []
    py_files = [
        f["path"] for f in pr["files"]["nodes"]
        if f["path"].endswith(".py") and "/tests/" not in f["path"]
    ]
    if len(py_files) > MAX_SURFACE_FILES:
        surface_notes.append(
            f"surface computed for the first {MAX_SURFACE_FILES} of {len(py_files)} changed Python files"
        )
        py_files = py_files[:MAX_SURFACE_FILES]
    for path in py_files:
        base_src = fetch_blob(args.repo, path, pr["baseRefOid"])
        head_src = fetch_blob(args.repo, path, pr["headRefOid"])
        if base_src is None and head_src is None:
            surface_notes.append(f"could not read either version of `{path}`")
            continue
        delta = surface_delta(base_src, head_src)
        for key, entries in delta.items():
            surface[key].extend(f"{path}: {entry}" for entry in entries)

    # Linked issues: explicit closing references plus Fixes/Closes in the body.
    numbers = [node["number"] for node in pr["closingIssuesReferences"]["nodes"]]
    for match in re.findall(r"(?:fix(?:e[sd])?|close[sd]?|resolve[sd]?)\s*:?\s*#(\d+)", pr["body"] or "", re.I):
        if int(match) not in numbers:
            numbers.append(int(match))
    issues = []
    for issue_number in numbers[:MAX_LINKED_ISSUES]:
        try:
            issue = graphql(ISSUE_QUERY, owner=owner, name=name, number=issue_number)["repository"]["issue"]
        except RuntimeError:
            issue = None
        if issue:
            issues.append(issue)

    terms = [] if args.no_prior_art else search_terms(pr["title"], surface)
    hits, prior_notes = prior_art(args.repo, args.number, terms) if terms else ([], [])
    if args.no_prior_art:
        prior_notes = ["prior-art search skipped (--no-prior-art)"]

    cache = args.cache or pathlib.Path("agents/impact/.cache") / f"open-prs-{args.repo.replace('/', '-')}.json"
    overlaps = overlapping_open_prs(cache, args.number, {f["path"] for f in pr["files"]["nodes"]})

    bundle = {
        "pr": pr, "diff": diff, "surface": surface, "surface_notes": surface_notes,
        "issues": issues, "terms": terms, "prior_art": hits,
        "prior_art_notes": prior_notes, "overlaps": overlaps,
    }

    text = json.dumps(bundle, indent=1) if args.json else render(bundle, args.diff_lines)
    if args.out:
        args.out.parent.mkdir(parents=True, exist_ok=True)
        args.out.write_text(text)
        print(f"wrote context bundle to {args.out}")
    else:
        print(text)
    return 0


 if __name__ == "__main__":
    sys.exit(main())
diff --git a/SKILL.md b/SKILL.md
Mode	Meaning	Count
default	touches scikit-learn source, no core-dev has commented or reviewed	106
`--featurey`	the above, restricted to `ENH`/`FEA`/`API`/`PRF` or a feature label	22
`--all`	every human non-draft PR	465
	#!/usr/bin/env python3
	"""Fetch every open PR of a repository into a local JSON cache via the GitHub GraphQL API.

	Only bulk metadata is fetched here: enough to apply the worklist filter without
	touching the REST search API, which is capped at 30 requests/minute. Per-PR
	detail (body, diff, discussion) is the job of pr_context.py.

	Page size is deliberately 25. Larger pages combined with the nested `files` and
	`comments` selections exceed GitHub's node limit, and the failure mode is an
	empty response body rather than an error, so it is easy to mistake for success.
	"""

	from __future__ import annotations

	import argparse
	import datetime as dt
	import json
	import pathlib
	import subprocess
	import sys
	import time

	DEFAULT_REPO = "scikit-learn/scikit-learn"
	PAGE_SIZE = 25

	QUERY = """
	query($owner: String!, $name: String!, $size: Int!, $cursor: String) {
	rateLimit { cost remaining resetAt }
	repository(owner: $owner, name: $name) {
	pullRequests(states: OPEN, first: $size, after: $cursor) {
	totalCount
	pageInfo { hasNextPage endCursor }
	nodes {
	number title url createdAt updatedAt isDraft
	additions deletions changedFiles
	author { login }
	authorAssociation
	labels(first: 20) { nodes { name } }
	comments(last: 40) { totalCount nodes { authorAssociation } }
	reviews(last: 40) { totalCount nodes { authorAssociation state } }
	files(first: 60) { totalCount nodes { path } }
	closingIssuesReferences(first: 5) { nodes { number title url } }
	}
	}
	}
	}
	"""


	class FetchError(RuntimeError):
	pass


	def run_graphql(owner: str, name: str, cursor: str \| None, size: int) -> dict:
	"""Execute one GraphQL page, with retries for transient and node-limit failures."""
	args = [
	"gh", "api", "graphql",
	"-f", f"query={QUERY}",
	"-F", f"owner={owner}",
	"-F", f"name={name}",
	"-F", f"size={size}",
	]
	if cursor:
	args += ["-F", f"cursor={cursor}"]

	last_problem = "unknown"
	for attempt in range(4):
	proc = subprocess.run(args, capture_output=True, text=True)

	# An empty body is the signature of exceeding the node limit. It is not
	# reported as an error, so it must be checked explicitly.
	if not proc.stdout.strip():
	last_problem = f"empty response body (exit {proc.returncode}): {proc.stderr.strip()[:300]}"
	else:
	try:
	payload = json.loads(proc.stdout)
	except json.JSONDecodeError as exc:
	last_problem = f"unparseable response: {exc}"
	else:
	if "errors" in payload:
	last_problem = "GraphQL errors: " + json.dumps(payload["errors"])[:300]
	elif not payload.get("data", {}).get("repository"):
	last_problem = "response contained no repository data"
	else:
	return payload

	if attempt < 3:
	time.sleep(2 * (attempt + 1))

	raise FetchError(last_problem)


	def fetch_all(owner: str, name: str, size: int, quiet: bool) -> tuple[list[dict], dict]:
	nodes: list[dict] = []
	cursor: str \| None = None
	cost = 0
	rate: dict = {}

	while True:
	payload = run_graphql(owner, name, cursor, size)
	rate = payload["data"]["rateLimit"]
	cost += rate["cost"]
	page = payload["data"]["repository"]["pullRequests"]
	nodes += page["nodes"]

	if not quiet:
	print(
	f" fetched {len(nodes)}/{page['totalCount']} open PRs",
	file=sys.stderr,
	)
	if not page["pageInfo"]["hasNextPage"]:
	break
	cursor = page["pageInfo"]["endCursor"]

	return nodes, {"cost": cost, "remaining": rate.get("remaining")}


	def cache_age_hours(path: pathlib.Path) -> float \| None:
	"""Age of the cache in hours, or None if it is absent or unreadable."""
	if not path.exists():
	return None
	try:
	stamp = json.loads(path.read_text())["fetched_at"]
	fetched = dt.datetime.fromisoformat(stamp)
	except (json.JSONDecodeError, KeyError, ValueError, OSError):
	return None
	if fetched.tzinfo is None:
	fetched = fetched.replace(tzinfo=dt.timezone.utc)
	delta = dt.datetime.now(dt.timezone.utc) - fetched
	return delta.total_seconds() / 3600.0


	def default_cache_path(repo: str) -> pathlib.Path:
	slug = repo.replace("/", "-")
	return pathlib.Path("agents/impact/.cache") / f"open-prs-{slug}.json"


	def main() -> int:
	parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
	parser.add_argument("--repo", default=DEFAULT_REPO, help=f"owner/name (default {DEFAULT_REPO})")
	parser.add_argument("--cache", type=pathlib.Path, help="cache file path")
	parser.add_argument(
	"--max-age-hours",
	type=float,
	default=24.0,
	help="reuse the cache if it is younger than this (default 24)",
	)
	parser.add_argument("--force", action="store_true", help="refetch regardless of cache age")
	parser.add_argument("--quiet", action="store_true", help="suppress progress output")
	args = parser.parse_args()

	if "/" not in args.repo:
	print(f"error: --repo must be owner/name, got {args.repo!r}", file=sys.stderr)
	return 2
	owner, name = args.repo.split("/", 1)

	cache = args.cache or default_cache_path(args.repo)
	age = cache_age_hours(cache)

	if not args.force and age is not None and age < args.max_age_hours:
	data = json.loads(cache.read_text())
	print(f"cache fresh ({age:.1f}h old): {data['count']} open PRs at {cache}")
	return 0

	if not args.quiet:
	reason = "no usable cache" if age is None else f"cache {age:.1f}h old"
	print(f"fetching {args.repo} ({reason})...", file=sys.stderr)

	try:
	nodes, usage = fetch_all(owner, name, PAGE_SIZE, args.quiet)
	except FetchError as exc:
	print(f"error: fetch failed: {exc}", file=sys.stderr)
	return 1

	cache.parent.mkdir(parents=True, exist_ok=True)
	cache.write_text(
	json.dumps(
	{
	"fetched_at": dt.datetime.now(dt.timezone.utc).isoformat(),
	"repo": args.repo,
	"count": len(nodes),
	"prs": nodes,
	},
	indent=1,
	)
	)

	truncated = [n["number"] for n in nodes if n["files"]["totalCount"] > 60]
	print(f"wrote {len(nodes)} open PRs to {cache} (rate-limit cost {usage['cost']}, {usage['remaining']} remaining)")
	if truncated:
	print(f"note: file lists truncated at 60 for PRs {truncated}")
	return 0


	if __name__ == "__main__":
	sys.exit(main())
	#!/usr/bin/env python3
	"""Apply the worklist filter to the open-PR cache and draw the next PR to brief.

	The default worklist is PRs that touch scikit-learn source and that no core
	developer has ever commented on or reviewed. Those are the PRs where the
	question "should we carry this?" has demonstrably never been asked.

	Core-dev engagement is detected via `authorAssociation` of MEMBER or OWNER on
	any comment or review. PRs authored by a core dev are deliberately kept when no
	other core dev has engaged: an unattended core-dev PR carries the same
	unanswered question.
	"""

	from __future__ import annotations

	import argparse
	import json
	import pathlib
	import random
	import re
	import sys

	CORE_ASSOCIATIONS = {"MEMBER", "OWNER"}
	FEATURE_TITLE = re.compile(r"^\s*(ENH\|FEA\|API\|PRF)\b", re.IGNORECASE)
	FEATURE_LABELS = {"New Feature", "Enhancement", "API"}
	DOC_SUFFIXES = (".rst", ".md", ".txt")
	# Leading commit-tag conventions stripped when building a filename slug.
	TITLE_TAG = re.compile(
	r"^\s*(ENH\|FEA\|FIX\|DOC\|MAINT\|CI\|TST\|BLD\|PRF\|API\|RFC\|CLN\|BUG\|POC\|WIP)[:\s]+",
	re.IGNORECASE,
	)


	def is_bot(pr: dict) -> bool:
	login = (pr.get("author") or {}).get("login") or ""
	return login.endswith("[bot]") or login in {"scikit-learn-bot", "dependabot"}


	def core_engaged(pr: dict) -> bool:
	for comment in pr["comments"]["nodes"]:
	if comment["authorAssociation"] in CORE_ASSOCIATIONS:
	return True
	for review in pr["reviews"]["nodes"]:
	if review["authorAssociation"] in CORE_ASSOCIATIONS:
	return True
	return False


	def core_approved(pr: dict) -> bool:
	return any(
	r["state"] == "APPROVED" and r["authorAssociation"] in CORE_ASSOCIATIONS
	for r in pr["reviews"]["nodes"]
	)


	def touches_sklearn_source(pr: dict) -> bool:
	for f in pr["files"]["nodes"]:
	path = f["path"]
	if not path.startswith("sklearn/"):
	continue
	if "/tests/" in path or path.startswith("sklearn/tests/"):
	continue
	if path.endswith((".py", ".pyx", ".pxd", ".pyx.tp")):
	return True
	return False


	def docs_only(pr: dict) -> bool:
	paths = [f["path"] for f in pr["files"]["nodes"]]
	if not paths:
	return False
	return all(
	p.startswith(("doc/", "examples/")) or p.endswith(DOC_SUFFIXES) for p in paths
	)


	def featurey(pr: dict) -> bool:
	labels = {node["name"] for node in pr["labels"]["nodes"]}
	return bool(FEATURE_TITLE.match(pr["title"]) or (labels & FEATURE_LABELS))


	def slug_for(pr: dict, words: int = 7) -> str:
	"""Deterministic filename slug, so the same PR always maps to the same file."""
	title = TITLE_TAG.sub("", pr["title"])
	cleaned = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
	parts = [part for part in cleaned.split("-") if part]
	return "-".join(parts[:words]) or "untitled"


	def modules_of(pr: dict) -> list[str]:
	return sorted(
	node["name"].removeprefix("module:")
	for node in pr["labels"]["nodes"]
	if node["name"].startswith("module:")
	)


	def build_worklist(prs: list[dict], mode: str) -> list[dict]:
	candidates = [p for p in prs if not p["isDraft"] and not is_bot(p)]
	if mode == "all":
	return candidates
	selected = [
	p
	for p in candidates
	if not core_engaged(p)
	and touches_sklearn_source(p)
	and not docs_only(p)
	and not core_approved(p)
	]
	if mode == "featurey":
	selected = [p for p in selected if featurey(p)]
	return selected


	def already_briefed(brief_dir: pathlib.Path) -> set[int]:
	"""PR numbers that already have a brief. Existence of the file is the state.

	Recursive, so filing a brief under `done/` still counts as briefed. Without
	that, archiving a brief would put its PR back in the draw.
	"""
	numbers: set[int] = set()
	if not brief_dir.exists():
	return numbers
	for path in brief_dir.rglob("*.md"):
	head = path.stem.split("-", 1)[0]
	if head.isdigit():
	numbers.add(int(head))
	return numbers


	def print_table(rows: list[dict], briefed: set[int]) -> None:
	for pr in rows:
	mark = "*" if pr["number"] in briefed else " "
	mods = ",".join(modules_of(pr)) or "-"
	print(
	f"{mark}#{pr['number']:<6} {pr['createdAt'][:7]} "
	f"+{pr['additions']:<5}/-{pr['deletions']:<5} "
	f"{pr['authorAssociation'][:22]:<22} {mods[:24]:<24} {pr['title'][:70]}"
	)


	def main() -> int:
	parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
	parser.add_argument("--cache", type=pathlib.Path, help="open-PR cache path")
	parser.add_argument("--repo", default="scikit-learn/scikit-learn")
	group = parser.add_mutually_exclusive_group()
	group.add_argument(
	"--featurey",
	action="store_const",
	const="featurey",
	dest="mode",
	help="narrow to public-surface additions only",
	)
	group.add_argument(
	"--all",
	action="store_const",
	const="all",
	dest="mode",
	help="widen to every human non-draft PR",
	)
	parser.add_argument(
	"--brief-dir",
	type=pathlib.Path,
	default=pathlib.Path("agents/impact"),
	help="directory of existing briefs (default agents/impact)",
	)
	parser.add_argument("--pick", type=int, metavar="N", help="draw N unbriefed PRs at random")
	parser.add_argument("--seed", type=int, help="seed the random draw for reproducibility")
	parser.add_argument("--include-briefed", action="store_true", help="do not skip briefed PRs")
	parser.add_argument("--json", action="store_true", help="emit JSON instead of a table")
	parser.add_argument("--counts", action="store_true", help="print filter cardinalities and exit")
	parser.set_defaults(mode="default")
	args = parser.parse_args()

	cache = args.cache or pathlib.Path("agents/impact/.cache") / f"open-prs-{args.repo.replace('/', '-')}.json"
	if not cache.exists():
	print(f"error: no cache at {cache}; run fetch_open_prs.py first", file=sys.stderr)
	return 1
	data = json.loads(cache.read_text())
	prs = data["prs"]

	if args.counts:
	print(f"cache fetched {data['fetched_at']} repo {data['repo']}")
	print(f"{'total open':46s} {len(prs)}")
	print(f"{' drafts':46s} {sum(1 for p in prs if p['isDraft'])}")
	print(f"{' bot-authored':46s} {sum(1 for p in prs if is_bot(p))}")
	for label, mode in [
	("--all (human, non-draft)", "all"),
	("default (unengaged + touches sklearn)", "default"),
	("--featurey", "featurey"),
	]:
	print(f"{label:46s} {len(build_worklist(prs, mode))}")
	return 0

	worklist = build_worklist(prs, args.mode)
	worklist.sort(key=lambda p: p["createdAt"])
	briefed = already_briefed(args.brief_dir)

	pool = worklist if args.include_briefed else [p for p in worklist if p["number"] not in briefed]

	if args.pick is not None:
	if not pool:
	print(
	f"worklist exhausted: all {len(worklist)} PRs in mode '{args.mode}' already have briefs "
	f"in {args.brief_dir}",
	file=sys.stderr,
	)
	return 3
	rng = random.Random(args.seed)
	pool = rng.sample(pool, min(args.pick, len(pool)))

	if args.json:
	print(
	json.dumps(
	[
	{
	"number": p["number"],
	"title": p["title"],
	"url": p["url"],
	"slug": slug_for(p),
	"brief_path": str(args.brief_dir / f"{p['number']}-{slug_for(p)}.md"),
	"created_at": p["createdAt"],
	"updated_at": p["updatedAt"],
	"author": (p.get("author") or {}).get("login"),
	"author_association": p["authorAssociation"],
	"additions": p["additions"],
	"deletions": p["deletions"],
	"changed_files": p["changedFiles"],
	"labels": [n["name"] for n in p["labels"]["nodes"]],
	"modules": modules_of(p),
	"featurey": featurey(p),
	"comment_count": p["comments"]["totalCount"],
	"review_count": p["reviews"]["totalCount"],
	"linked_issues": [
	{"number": c["number"], "title": c["title"], "url": c["url"]}
	for c in p["closingIssuesReferences"]["nodes"]
	],
	"already_briefed": p["number"] in briefed,
	}
	for p in pool
	],
	indent=1,
	)
	)
	return 0

	print_table(pool, briefed)
	suffix = "" if args.include_briefed else f", {len(briefed & {p['number'] for p in worklist})} already briefed and skipped"
	print(f"\n{len(pool)} PRs shown (mode '{args.mode}', worklist {len(worklist)}{suffix})")
	return 0


	if __name__ == "__main__":
	sys.exit(main())
	#!/usr/bin/env python3
	"""Assemble the deterministic context bundle for one PR.

	Everything here is mechanical and sourced. The judgment that this bundle feeds
	-- reach, counterfactual availability, cost, and the questions the decision
	hinges on -- is the model's job, not this script's.

	Four things are gathered:

	1. PR metadata, body, and the diff.
	2. Linked issues with their discussion, which is usually where the only
	statement of user impact lives.
	3. The public API surface delta, computed by parsing the base and head versions
	of each changed Python file with `ast` and comparing them. Path heuristics do
	not work for scikit-learn, whose public names live in privately-named files
	such as `_classification.py`, so the surface is derived from the code itself.
	4. Prior art: earlier issues and PRs proposing the same thing, plus other open
	PRs touching the same files. The latter comes from the local cache at zero
	API cost and is how overlapping PRs get noticed.
	"""

	from __future__ import annotations

	import argparse
	import ast
	import base64
	import json
	import pathlib
	import re
	import subprocess
	import sys
	import time

	DEFAULT_REPO = "scikit-learn/scikit-learn"
	# The REST search API allows 30 requests/minute. Stay well under it.
	SEARCH_SLEEP_S = 2.5
	MAX_SEARCH_QUERIES = 5
	MAX_SURFACE_FILES = 12
	MAX_LINKED_ISSUES = 6

	PR_QUERY = """
	query($owner: String!, $name: String!, $number: Int!) {
	repository(owner: $owner, name: $name) {
	pullRequest(number: $number) {
	number title url body state isDraft createdAt updatedAt
	additions deletions changedFiles
	author { login }
	authorAssociation
	baseRefName headRefName baseRefOid headRefOid
	isCrossRepository
	headRepository { nameWithOwner }
	labels(first: 25) { nodes { name } }
	files(first: 100) { totalCount nodes { path additions deletions } }
	comments(first: 60) {
	totalCount
	nodes { author { login } authorAssociation createdAt body }
	}
	reviews(first: 40) {
	totalCount
	nodes { author { login } authorAssociation state submittedAt body }
	}
	closingIssuesReferences(first: 10) { nodes { number } }
	}
	}
	}
	"""

	ISSUE_QUERY = """
	query($owner: String!, $name: String!, $number: Int!) {
	repository(owner: $owner, name: $name) {
	issue(number: $number) {
	number title url state stateReason createdAt closedAt body
	author { login }
	reactions { totalCount }
	labels(first: 25) { nodes { name } }
	comments(first: 40) {
	totalCount
	nodes { author { login } authorAssociation createdAt body }
	}
	}
	}
	}
	"""

	STOPWORDS = {
	"add", "adds", "added", "adding", "allow", "allows", "and", "any", "are", "avoid",
	"based", "better", "between", "bug", "but", "can", "case", "cases", "change",
	"changes", "check", "class", "common", "correct", "data", "default", "deprecate",
	"doc", "docs", "does", "dont", "during", "else", "ensure", "error", "example",
	"examples", "fail", "failing", "fails", "fix", "fixed", "fixes", "for", "from",
	"function", "handle", "handling", "has", "have", "improve", "improved", "input",
	"instead", "into", "issue", "make", "makes", "method", "methods", "missing",
	"more", "new", "not", "now", "only", "option", "parameter", "parameters", "pass",
	"raise", "raises", "remove", "removed", "return", "returns", "same", "set",
	"should", "small", "some", "support", "test", "tests", "that", "the", "their",
	"then", "there", "this", "throw", "use", "used", "using", "value", "values",
	"when", "where", "which", "with", "without", "wrong",
	}


	# --------------------------------------------------------------------------- gh


	def gh(args: list[str]) -> str:
	proc = subprocess.run(args, capture_output=True, text=True)
	if proc.returncode != 0 or not proc.stdout.strip():
	raise RuntimeError(f"{' '.join(args[:3])} failed: {proc.stderr.strip()[:300]}")
	return proc.stdout


	def graphql(query: str, **variables) -> dict:
	args = ["gh", "api", "graphql", "-f", f"query={query}"]
	for key, value in variables.items():
	args += ["-F", f"{key}={value}"]
	payload = json.loads(gh(args))
	if "errors" in payload:
	raise RuntimeError("GraphQL errors: " + json.dumps(payload["errors"])[:300])
	return payload["data"]


	def fetch_blob(repo: str, path: str, ref: str) -> str \| None:
	"""File contents at a ref. Works for fork head SHAs via the base repo."""
	try:
	raw = gh(["gh", "api", f"repos/{repo}/contents/{path}?ref={ref}"])
	except RuntimeError:
	return None
	try:
	node = json.loads(raw)
	if node.get("encoding") != "base64":
	return None
	return base64.b64decode(node["content"]).decode("utf-8", errors="replace")
	except (json.JSONDecodeError, KeyError, ValueError):
	return None


	# ----------------------------------------------------------- public API surface


	def _params(node: ast.FunctionDef \| ast.AsyncFunctionDef) -> dict[str, str]:
	"""Parameter name -> rendered default ('' when the parameter is required)."""
	out: dict[str, str] = {}
	pos = list(node.args.posonlyargs) + list(node.args.args)
	defaults = list(node.args.defaults)
	pad = len(pos) - len(defaults)
	for index, arg in enumerate(pos):
	if arg.arg == "self":
	continue
	default = defaults[index - pad] if index >= pad else None
	out[arg.arg] = _render(default)
	if node.args.vararg:
	out["*" + node.args.vararg.arg] = ""
	for arg, default in zip(node.args.kwonlyargs, node.args.kw_defaults):
	out[arg.arg] = _render(default)
	if node.args.kwarg:
	out["**" + node.args.kwarg.arg] = ""
	return out


	def _render(node: ast.AST \| None) -> str:
	if node is None:
	return ""
	try:
	return ast.unparse(node)
	except Exception:
	return "?"


	def public_surface(source: str) -> dict:
	"""Public functions, classes and methods with their parameters.

	`__init__` is treated as public because for a scikit-learn estimator its
	parameters are the public API.
	"""
	try:
	tree = ast.parse(source)
	except SyntaxError:
	return {}
	surface: dict[str, dict[str, str]] = {}
	for node in tree.body:
	if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
	if not node.name.startswith("_"):
	surface[node.name] = _params(node)
	elif isinstance(node, ast.ClassDef) and not node.name.startswith("_"):
	surface[node.name + " (class)"] = {}
	for item in node.body:
	if not isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
	continue
	if item.name.startswith("_") and item.name != "__init__":
	continue
	surface[f"{node.name}.{item.name}"] = _params(item)
	return surface


	def surface_delta(base_src: str \| None, head_src: str \| None) -> dict:
	"""Added/removed callables, and added/removed/retyped parameters."""
	base = public_surface(base_src) if base_src else {}
	head = public_surface(head_src) if head_src else {}
	delta: dict[str, list] = {
	"added_callables": sorted(set(head) - set(base)),
	"removed_callables": sorted(set(base) - set(head)),
	"added_params": [],
	"removed_params": [],
	"changed_defaults": [],
	}
	for name in sorted(set(base) & set(head)):
	before, after = base[name], head[name]
	for param in sorted(set(after) - set(before)):
	default = after[param]
	delta["added_params"].append(
	f"{name}({param}{'=' + default if default else ''})"
	)
	for param in sorted(set(before) - set(after)):
	delta["removed_params"].append(f"{name}({param})")
	for param in sorted(set(before) & set(after)):
	if before[param] != after[param]:
	delta["changed_defaults"].append(
	f"{name}({param}): {before[param] or '<required>'} -> {after[param] or '<required>'}"
	)
	return delta


	# ------------------------------------------------------------------ prior art


	def search_terms(title: str, surface: dict) -> list[str]:
	"""Distinctive identifiers worth searching history for."""
	terms: list[str] = []
	for match in re.findall(r"`([^`]+)`", title):
	terms.append(match.strip())
	for match in re.findall(r"\b([A-Z][a-zA-Z0-9][a-z][a-zA-Z0-9][A-Z][a-zA-Z0-9]*)\b", title):
	terms.append(match)
	for entry in surface.get("added_params", []):
	name = re.search(r"\(([^=)]+)", entry)
	if name:
	terms.append(name.group(1))
	for entry in surface.get("added_callables", []):
	terms.append(entry.replace(" (class)", "").split(".")[-1])
	for word in re.findall(r"\b[a-z][a-z_]{4,}\b", title.lower()):
	if word not in STOPWORDS:
	terms.append(word)

	seen: list[str] = []
	for term in terms:
	term = term.strip().strip("`'\"")
	if len(term) < 4 or term.lower() in STOPWORDS:
	continue
	if term.lower() not in {t.lower() for t in seen}:
	seen.append(term)
	return seen[:MAX_SEARCH_QUERIES]


	def is_identifier_like(term: str) -> bool:
	"""Code identifiers are high-precision search terms; bare English words are not."""
	return "_" in term or any(c.isupper() for c in term)


	def prior_art(repo: str, number: int, terms: list[str]) -> tuple[list[dict], list[str]]:
	"""Earlier issues and PRs mentioning the same identifiers.

	Broad single-word terms are capped hard. Searching scikit-learn history for
	a word like "categorical" returns dozens of unrelated hits that bury the one
	result that matters, which is usually a previous attempt at the same change.
	"""
	hits: dict[int, dict] = {}
	notes: list[str] = []
	# Search the precise terms first, so the per-term budget is spent well.
	ordered = sorted(terms, key=lambda t: not is_identifier_like(t))
	for index, term in enumerate(ordered):
	if index:
	time.sleep(SEARCH_SLEEP_S)
	broad = not is_identifier_like(term)
	cap = 4 if broad else 25
	query = f'repo:{repo} "{term}" in:title'
	try:
	raw = gh([
	"gh", "api", "-X", "GET", "search/issues",
	"-f", f"q={query}", "-f", "per_page=30",
	"-f", "sort=created", "-f", "order=desc",
	])
	except RuntimeError as exc:
	notes.append(f"search for {term!r} failed ({str(exc)[:80]}) -- prior art may be incomplete")
	continue
	try:
	payload = json.loads(raw)
	items = payload.get("items", [])
	except json.JSONDecodeError:
	notes.append(f"search for {term!r} returned unparseable JSON")
	continue
	if broad and payload.get("total_count", 0) > cap:
	notes.append(
	f"{term!r} is a broad term with {payload['total_count']} title matches; "
	f"showing the {cap} most recent only"
	)
	for item in items[:cap]:
	if item["number"] == number:
	continue
	hits.setdefault(item["number"], {
	"number": item["number"],
	"title": item["title"],
	"url": item["html_url"],
	"kind": "pr" if "pull_request" in item else "issue",
	"state": item["state"],
	"merged": bool(item.get("pull_request", {}).get("merged_at")),
	"created_at": item["created_at"][:10],
	"closed_at": (item.get("closed_at") or "")[:10],
	"matched": term,
	})
	return sorted(hits.values(), key=lambda h: h["created_at"]), notes


	def overlapping_open_prs(cache: pathlib.Path, number: int, paths: set[str]) -> list[dict]:
	"""Other open PRs touching the same files. Read from the cache, no API cost."""
	if not cache.exists():
	return []
	try:
	prs = json.loads(cache.read_text())["prs"]
	except (json.JSONDecodeError, KeyError, OSError):
	return []
	out = []
	for pr in prs:
	if pr["number"] == number:
	continue
	shared = paths & {f["path"] for f in pr["files"]["nodes"]}
	if shared:
	out.append({
	"number": pr["number"],
	"title": pr["title"],
	"url": pr["url"],
	"created_at": pr["createdAt"][:10],
	"is_draft": pr["isDraft"],
	"shared_files": sorted(shared),
	})
	return sorted(out, key=lambda p: -len(p["shared_files"]))


	# --------------------------------------------------------------------- render


	def truncate(text: str \| None, limit: int) -> str:
	text = (text or "").strip()
	if len(text) <= limit:
	return text or "(empty)"
	return text[:limit] + f"\n... [truncated, {len(text) - limit} more characters]"


	def render(bundle: dict, diff_lines: int) -> str:
	pr = bundle["pr"]
	out: list[str] = []
	add = out.append

	add(f"# Context bundle: PR #{pr['number']} -- {pr['title']}")
	add("")
	add(f"- URL: {pr['url']}")
	add(f"- Author: {(pr.get('author') or {}).get('login')} ({pr['authorAssociation']})")
	add(f"- Opened {pr['createdAt'][:10]}, last updated {pr['updatedAt'][:10]}")
	add(f"- Size: +{pr['additions']}/-{pr['deletions']} across {pr['changedFiles']} files")
	add(f"- Labels: {', '.join(n['name'] for n in pr['labels']['nodes']) or 'none'}")
	add(f"- Base {pr['baseRefName']} @ {pr['baseRefOid'][:9]}, head {pr['headRefName']} @ {pr['headRefOid'][:9]}")
	add(f"- Comments: {pr['comments']['totalCount']}, reviews: {pr['reviews']['totalCount']}")
	add("")

	add("## PR body")
	add("")
	add(truncate(pr["body"], 4000))
	add("")

	add("## Changed files")
	add("")
	for f in pr["files"]["nodes"]:
	add(f"- `{f['path']}` +{f['additions']}/-{f['deletions']}")
	if pr["files"]["totalCount"] > len(pr["files"]["nodes"]):
	add(f"- ... {pr['files']['totalCount'] - len(pr['files']['nodes'])} more files")
	add("")

	add("## Public API surface delta")
	add("")
	add("Computed by parsing base and head with `ast`. Empty means this PR adds no public surface.")
	add("")
	add("Caveat: this is a per-file, per-class view and does not follow inheritance. A method "
	"moved to a new base class shows up as both removed and added, which is a refactor "
	"rather than a removal of public API. Check the diff before describing anything as removed.")
	add("")
	surface = bundle["surface"]
	if not any(surface.get(k) for k in ("added_callables", "removed_callables", "added_params", "removed_params", "changed_defaults")):
	add("No public API surface change detected.")
	else:
	for key, label in [
	("added_callables", "New public callables"),
	("removed_callables", "Removed public callables"),
	("added_params", "New parameters"),
	("removed_params", "Removed parameters"),
	("changed_defaults", "Changed defaults (behaviour change for existing users)"),
	]:
	if surface.get(key):
	add(f"{label}:")
	for entry in surface[key]:
	add(f"- `{entry}`")
	add("")
	for note in bundle["surface_notes"]:
	add(f"- note: {note}")
	add("")

	add("## Linked issues")
	add("")
	if not bundle["issues"]:
	add("No linked issue. The PR body is the only statement of motivation.")
	for issue in bundle["issues"]:
	state = issue["state"] + (f"/{issue['stateReason']}" if issue.get("stateReason") else "")
	add(f"### #{issue['number']} {issue['title']} [{state}]")
	add("")
	add(f"{issue['url']} -- opened {issue['createdAt'][:10]} by "
	f"{(issue.get('author') or {}).get('login')}, "
	f"{issue['reactions']['totalCount']} reactions, "
	f"{issue['comments']['totalCount']} comments")
	add(f"Labels: {', '.join(n['name'] for n in issue['labels']['nodes']) or 'none'}")
	add("")
	add(truncate(issue["body"], 2500))
	add("")
	if issue["comments"]["nodes"]:
	add("Discussion:")
	add("")
	for comment in issue["comments"]["nodes"]:
	who = (comment.get("author") or {}).get("login")
	add(f"- {who} ({comment['authorAssociation']}, {comment['createdAt'][:10]}): "
	f"{truncate(comment['body'], 700)}")
	add("")

	add("## PR discussion")
	add("")
	if not pr["comments"]["nodes"] and not pr["reviews"]["nodes"]:
	add("None. Nobody has said anything on this PR.")
	for comment in pr["comments"]["nodes"]:
	who = (comment.get("author") or {}).get("login")
	add(f"- {who} ({comment['authorAssociation']}, {comment['createdAt'][:10]}): "
	f"{truncate(comment['body'], 700)}")
	for review in pr["reviews"]["nodes"]:
	who = (review.get("author") or {}).get("login")
	add(f"- {who} review {review['state']} ({review['authorAssociation']}, "
	f"{(review.get('submittedAt') or '')[:10]}): {truncate(review['body'], 700)}")
	add("")

	add("## Prior art: history mentioning the same identifiers")
	add("")
	add(f"Search terms: {', '.join(bundle['terms']) or 'none derived'}")
	add("")
	if not bundle["prior_art"]:
	add("No earlier issues or PRs found for these terms.")
	for hit in bundle["prior_art"]:
	status = "merged" if hit["merged"] else hit["state"]
	closed = f", closed {hit['closed_at']}" if hit["closed_at"] else ""
	add(f"- [{hit['kind']} #{hit['number']}]({hit['url']}) [{status}] "
	f"created {hit['created_at']}{closed} -- {hit['title']} (matched `{hit['matched']}`)")
	for note in bundle["prior_art_notes"]:
	add(f"- note: {note}")
	add("")

	add("## Other open PRs touching the same files")
	add("")
	if not bundle["overlaps"]:
	add("None.")
	for overlap in bundle["overlaps"]:
	draft = " (draft)" if overlap["is_draft"] else ""
	add(f"- [#{overlap['number']}]({overlap['url']}){draft} opened {overlap['created_at']} -- "
	f"{overlap['title']} -- shares {', '.join('`' + p + '`' for p in overlap['shared_files'])}")
	add("")

	add("## Diff")
	add("")
	diff = bundle["diff"].splitlines()
	if len(diff) > diff_lines:
	add(f"Truncated to the first {diff_lines} of {len(diff)} lines.")
	add("")
	diff = diff[:diff_lines]
	add("```diff")
	out.extend(diff)
	add("```")
	return "\n".join(out)


	# ----------------------------------------------------------------------- main


	def main() -> int:
	parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
	parser.add_argument("number", type=int, help="PR number")
	parser.add_argument("--repo", default=DEFAULT_REPO)
	parser.add_argument("--out", type=pathlib.Path, help="write to this path instead of stdout")
	parser.add_argument("--json", action="store_true", help="emit the raw bundle as JSON")
	parser.add_argument("--diff-lines", type=int, default=2000, help="cap on diff lines (default 2000)")
	parser.add_argument("--no-prior-art", action="store_true", help="skip the throttled history search")
	parser.add_argument("--cache", type=pathlib.Path, help="open-PR cache, for overlap detection")
	args = parser.parse_args()

	owner, name = args.repo.split("/", 1)
	try:
	pr = graphql(PR_QUERY, owner=owner, name=name, number=args.number)["repository"]["pullRequest"]
	except RuntimeError as exc:
	print(f"error: could not fetch PR #{args.number}: {exc}", file=sys.stderr)
	return 1
	if pr is None:
	print(f"error: PR #{args.number} not found in {args.repo}", file=sys.stderr)
	return 1

	try:
	diff = gh(["gh", "pr", "diff", str(args.number), "--repo", args.repo])
	except RuntimeError as exc:
	diff = f"(diff unavailable: {exc})"

	# Public API surface delta, per changed Python file.
	surface: dict[str, list] = {
	"added_callables": [], "removed_callables": [],
	"added_params": [], "removed_params": [], "changed_defaults": [],
	}
	surface_notes: list[str] = []
	py_files = [
	f["path"] for f in pr["files"]["nodes"]
	if f["path"].endswith(".py") and "/tests/" not in f["path"]
	]
	if len(py_files) > MAX_SURFACE_FILES:
	surface_notes.append(
	f"surface computed for the first {MAX_SURFACE_FILES} of {len(py_files)} changed Python files"
	)
	py_files = py_files[:MAX_SURFACE_FILES]
	for path in py_files:
	base_src = fetch_blob(args.repo, path, pr["baseRefOid"])
	head_src = fetch_blob(args.repo, path, pr["headRefOid"])
	if base_src is None and head_src is None:
	surface_notes.append(f"could not read either version of `{path}`")
	continue
	delta = surface_delta(base_src, head_src)
	for key, entries in delta.items():
	surface[key].extend(f"{path}: {entry}" for entry in entries)

	# Linked issues: explicit closing references plus Fixes/Closes in the body.
	numbers = [node["number"] for node in pr["closingIssuesReferences"]["nodes"]]
	for match in re.findall(r"(?:fix(?:e[sd])?\|close[sd]?\|resolve[sd]?)\s:?\s#(\d+)", pr["body"] or "", re.I):
	if int(match) not in numbers:
	numbers.append(int(match))
	issues = []
	for issue_number in numbers[:MAX_LINKED_ISSUES]:
	try:
	issue = graphql(ISSUE_QUERY, owner=owner, name=name, number=issue_number)["repository"]["issue"]
	except RuntimeError:
	issue = None
	if issue:
	issues.append(issue)

	terms = [] if args.no_prior_art else search_terms(pr["title"], surface)
	hits, prior_notes = prior_art(args.repo, args.number, terms) if terms else ([], [])
	if args.no_prior_art:
	prior_notes = ["prior-art search skipped (--no-prior-art)"]

	cache = args.cache or pathlib.Path("agents/impact/.cache") / f"open-prs-{args.repo.replace('/', '-')}.json"
	overlaps = overlapping_open_prs(cache, args.number, {f["path"] for f in pr["files"]["nodes"]})

	bundle = {
	"pr": pr, "diff": diff, "surface": surface, "surface_notes": surface_notes,
	"issues": issues, "terms": terms, "prior_art": hits,
	"prior_art_notes": prior_notes, "overlaps": overlaps,
	}

	text = json.dumps(bundle, indent=1) if args.json else render(bundle, args.diff_lines)
	if args.out:
	args.out.parent.mkdir(parents=True, exist_ok=True)
	args.out.write_text(text)
	print(f"wrote context bundle to {args.out}")
	else:
	print(text)
	return 0


	if __name__ == "__main__":
	sys.exit(main())
name	pr-impact-brief
description	Assemble source-linked evidence on whether a scikit-learn PR is worth carrying, one PR at a time, ending in the questions the decision hinges on and never in a verdict. Use when the user says "let's review some PRs for worth", asks to review or triage PRs for worth or impact, asks whether a PR is worth it or worth merging or worth carrying, or asks for an impact brief on a PR number or URL.
Script	Purpose
`scripts/fetch_open_prs.py`	Paginated GraphQL fetch of every open PR into a JSON cache
`scripts/filter_prs.py`	Applies the worklist filter; draws the next PR at random
`scripts/pr_context.py`	Per-PR context bundle: diff, linked issues, public-surface delta, prior art