Github Research

GitHub Research

Overview

Collects evidence from GitHub: repos, code, issues, PRs, releases, discussions, commits. Each output is one evidence record — a claim backed by a verbatim quote pinned to a permanent anchor (commit SHA, not a branch that can move). This skill never concludes or synthesizes; it produces raw material for state/runs/<slug>/evidence.jsonl.

Layer rule: produces evidence, not results. Synthesis and confidence status are the orchestrator's job.

When to use

Direct use: "find repos that do X", "what does the changelog say about Y", "check if this bug is still open". As a component: orchestrator dispatches this alongside web/reddit research for implementation-type claims.

Don't use for: general web content (→ web-research), Reddit discussion even if it's about a GitHub project (→ reddit-research), writing/editing code in the current project (not a research task).

Capability check (once per session, not per query)

Run gh auth status first. Authenticated unlocks code search (unavailable anonymously — GitHub returns 401 with no anonymous mode, not a rate limit to route around) and higher limits. See references/tooling.md for the full chain and measured rate limits.

Workflow

1. Pick the right search surface for the question:
   • Repo discovery → gh search repos (topic/stars/language filters)
   • "How is X implemented" → gh search code (auth required; returns textMatches — the verbatim quote, direct from the API)
   • "Is this a known issue" / demand signal → gh search issues sorted by reactions, or gh api .../issues/N/comments
   • "What changed in version Y" → gh release view/gh release list (publish date comes free)
   • Community discussion on the repo → GraphQL search(type:DISCUSSION, ...) (not covered by gh search) Exact commands are in references/tooling.md — use them verbatim, don't improvise flag names.
2. Go past the README when the claim is "this is actually implemented/used". A repo existing, or its README claiming a feature, is not evidence the feature works. Follow the depth ladder: README → repo structure → the actual file implementing the claim → issues/PRs discussing it → releases confirming it shipped. Set quality.repro.type honestly: actual-run only when the record shows a real command/code and its result; maintainer-confirmed when the author asserts it works without showing a run. Only actual-run satisfies the implementation bar for confirmed (engine/ranking.md) — "the maintainer said yes" is testimony, not reproduction.
3. Root follows who is speaking, not where the evidence lives. The project's own artifacts — README, docs, code, releases, commits, maintainer statements — are one project speaking regardless of which of these you quote: root_id: github:owner/repo. But an outside, unaffiliated user's issue, comment, or reproduction is that person's voice, not the project's — root_id: person:<username>, per engine/origin-tracing.md. Getting this backwards in either direction breaks independence counting: collapsing an outside reporter into github:owner/repo erases real third-party corroboration (two unaffiliated users independently hitting the same bug are two roots, not one); conversely, assigning the maintainer's own release notes a person: id manufactures false independence for a claim the project is making about itself. Decide by checking who wrote the specific artifact you're quoting — the repo owner/org, a listed maintainer, or an unrelated contributor/reporter — not by which repo it's filed under.
4. If a search returns nothing: run references/query-relaxation.md, dropping the language filter first, then reducing to core terms, then a single term. Log full exhaustion as a gap.
5. Pin the quote correctly:
   • Code: rewrite any blob/main/...-style URL to blob/<full-sha>/... before recording it — branch-pinned URLs drift.
   • Comments: record created_at as published_at AND updated_at as modified_at — an edited comment quoted from stale memory is a trap.
   • Code search hits carry no date; follow up with gh api repos/.../commits?path=...&per_page=1 for the commit date.
6. Archive per references/citation-rules.md.
7. Assign tier per references/source-tiers.md's github table (repo's own source/README/releases = tier 1; maintainer comments on their own issues = tier 3; drive-by comments/unmerged PRs = tier 4) and purpose.
8. Write the evidence record per engine/evidence-contract.md, verification_status: pending. Do not self-verify.

Output

One evidence record per claim, appended to the run's evidence.jsonl.

Common mistakes