Github Solution Research

---
name: github-solution-research
description: 'Use when facing a bug, integration failure, dependency issue, unclear API usage, implementation blocker, or tool capability need and the user wants open-source solutions from GitHub. Searches issues, PRs, code, and repositories via `gh`, ranks by problem fit, and returns a reuse/adapt/avoid recommendation with a verification command. Not for source or remote-system changes.'
---

# GitHub solution research

## Contract

| Field | Bound contract |
|---|---|
| Trigger | Facing a bug, integration failure, dependency issue, unclear API usage, implementation blocker, or tool capability need. |
| Authority | Read-only: runs `gh` searches and optional read-only research subagents; reads local code, logs, and config; no file, VCS, credential, paid, published, deployed, or remote mutation. |
| Side effect | Chat output only: a recommendation with reuse/adapt/avoid, a verification command, and a confidence label when evidence is weak. |
| Done | A report containing a local problem profile, the search path, key evidence with links, a recommended reuse/adapt/avoid, a verification command, and a confidence label when evidence is weak. |

## Inputs

- The concrete problem: goal, symptom or error signature, reproduction path, versions, runtime, dependency/framework names, recent changes, constraints, and attempted fixes. Inspect local files and logs to fill discoverable facts before asking.
- Optional: explicit authorization to inspect private repositories. Do not inspect private repositories unless the user explicitly scopes and authorizes that access.

## Procedure

1. Frame the problem locally first. Capture goal, symptom/error, reproduction path, versions, runtime, dependency/framework names, recent changes, constraints, and attempted fixes. Inspect local files and logs before asking for any discoverable fact. Done when: the problem is framed with all discoverable facts filled from local sources.
2. Choose the evidence mode. For errors/regressions, search issues, PRs, releases, and code first. For capability or tool needs, search repository candidates first. For feature implementation, use both repository candidates and issue/PR/code evidence. Done when: the evidence mode is chosen and justified by the problem type.
3. Decide whether read-only research subagents would improve breadth, evidence quality, or review coverage. Use them only when the problem spans 2+ independent ecosystems, repository discovery needs broad candidate coverage, evidence can be split cleanly by project/version/surface, or the final recommendation would benefit from independent review. Skip them for narrow single-surface errors, when local context must be understood before external research, or when rate limits, private repositories, secrets, or sensitive logs make delegation risky. State the reason when subagents are skipped. Done when: the subagent decision is made and stated.
4. Create targeted searches. Prefer exact error text, package/API names, version numbers, framework + symptom, file names, config keys, stack trace fragments, failing command names, or capability + framework/runtime/API names. Start narrow, then add constraints (version, language, platform, deployment target, bundler, database, auth provider, runtime). Done when: targeted search queries are constructed.
5. Use the GitHub CLI (`gh`) as the default search and inspection surface. Prefer `gh search repos`, `gh search issues`, `gh search prs`, `gh search code`, `gh repo view`, `gh issue view`, `gh pr view`, and `gh api` before browser scraping or custom scripts. Adjust query, repo, fields, and limits to the local problem. Run `gh auth status` only when a command fails with 403, 429, a private-repository authorization error, or an explicit not-authenticated message; inspect the emitted rate-limit or authorization context before retrying, reducing breadth, or switching endpoints. Done when: the GitHub CLI searches are executed and results collected.
6. Search evidence surfaces in this order when relevant: issues/PRs/discussions, merged fixes, release notes/changelog, examples/templates, source code, then repository-level candidates. For implementation blockers without an error, search the desired capability plus framework/runtime/API names. For public platform data needs (trends, hot lists, topic search, engagement metrics), look for reusable public endpoints, open-source crawlers, archived datasets, and API field evidence before browser scraping; verify the chosen source with a minimal real request and separate anonymous hot-list data from logged-in search/topic data. Done when: all relevant evidence surfaces are searched in priority order.
7. Find suitable GitHub projects when a project itself may solve the problem. Prefer high-fit, high-Star, active, non-archived repositories with clear licenses and real examples. Lower the Star threshold when the high-Star set is too broad or misses the exact problem. Record Stars, forks, language, license, activity, and basic content. Done when: candidate projects are identified with metadata recorded.
8. Rank by problem fit first. Maintainer-confirmed issues, merged PRs, released fixes, official examples, and exact matching code beat popular adjacent projects. Use Stars and forks only as supporting maturity context and tie-breakers among similarly fitting repositories. Demote matches that are old, version-mismatched, archived, unresolved, speculative, or based only on user guesses. For security, auth, payments, infrastructure, or production operations, cross-check findings against current official docs or repositories when facts may have changed. Done when: candidates are ranked by problem fit with tie-breakers applied.
9. Deep-read the strongest projects and evidence. Extract project basics, reusable surfaces, root cause or implementation pattern, version constraints, risks, adaptation boundaries, and verification steps. For each serious evidence item identify: exact match (same error, behavior, API, version, environment, workflow); evidence strength (maintainer confirmation, merged PR, released fix, reproducible code example, test fixture, repeated independent reports); applicability (conditions that must match locally); implementation value (patch, config, API usage, dependency version, workflow, test, operational pattern); and risk (stale version, unresolved issue, unsafe workaround, license concern, security/privacy impact, deployment mismatch, overbroad change). Done when: the strongest evidence is deep-read with all six dimensions populated per item.
10. When using subagents, define each subagent's query family, repository scope, evidence surface, constraints, allowed write scope, and expected output; require direct links, verified metadata, problem-fit rationale, risk notes, and explicit rejection reasons; keep subagents read-only; merge and deduplicate results before ranking (do not count repeated reports of the same issue, PR, code path, or repository as independent evidence); and directly verify the strongest claims with `gh`, source reads, tests, logs, real requests, or official docs before finalizing. Done when: subagent results are merged, deduplicated, and strongest claims verified.
11. Translate to local work with minimal adaptation. Prefer the existing GitHub solution's public workflow, API, or architecture. Adapt only the parts required by the user's local interfaces, configuration, data/auth model, deployment target, or language/runtime. Prefer reading patterns and reusing existing public interfaces over copying code; if code reuse is necessary, check the license and keep attribution/obligation risks visible. Avoid large rewrites of an existing GitHub solution and large verbatim excerpts from repositories, READMEs, issues, PRs, or documentation. Done when: the local adaptation plan is defined with license obligations visible.
12. If evidence is weak, do not stretch weak matches into a confident recommendation. Mark the recommendation as first-principles or local-only when GitHub evidence is insufficient. Done when: the confidence label is set honestly.

## Failure and recovery

- Network or `gh` access unavailable: state that GitHub research could not be performed and mark the recommendation as local-only. Do not fabricate evidence.
- GitHub 403/429 or authorization error: inspect the emitted rate-limit or authorization context before retrying, reducing breadth, or switching endpoints. Do not paste or persist tokens, cookies, private repository contents, or credentials in prompts, files, logs, or memory; do not pass tokens, cookies, private repository contents, sensitive logs, secrets, production data, or credentials to subagents.
- Weak or no strong GitHub solution: mark the recommendation first-principles or local-only with a confidence label; do not let external examples override local constraints.
- Private repository access not explicitly authorized: do not inspect; treat as out of scope.
- Partial results: report what was found and what could not be verified; never swallow errors or pretend the done predicate holds. No file, VCS, credential, or remote mutation occurs, so no rollback is required.

## Output

A report containing: a local problem profile (goal, symptom/error, versions/environment, local constraints); the search path (queries or discovery methods used, GitHub surfaces searched, whether subagents were used or skipped); a subagent trace when subagents were used (each subagent's scope, evidence surfaces, key findings, rejected candidates, deduplication results, and which claims the controller directly verified); project candidates when a GitHub project is relevant (repo link, Stars, forks, language, license, activity, basic content, match rationale, local use) in a compact table; key evidence (links to issues, PRs, code, examples, releases, or repos, with match rationale); a recommended solution (what to reuse directly, what to adapt locally, what to avoid copying, and why it fits); rejected or risky options with reasons; a verification standard (test, build, reproduction command, real request, or manual check required to confirm the fix); and a confidence label when evidence is weak or no strong GitHub solution was found. For website, SaaS, landing-page, theme, or frontend-template candidates, include both the repository URL and the live preview/demo URL for every serious candidate; if no preview is available or verified, state that and downgrade the candidate. Do not answer with only links, Stars, or popularity rankings, and do not write "common GitHub pattern" without linked evidence.