Pavedpath Code

PavedPath Code

PavedPath Code（代码版）helps agents avoid reinventing solutions for software engineering problems. It searches GitHub and open-source evidence for proven implementation paths, then adapts the strongest pattern to the local codebase with minimal, verifiable changes.

Use GitHub as a primary evidence source, not as a link dump. The goal is to define the local code problem, find paths already walked in public repositories, issues, pull requests, discussions, examples, release notes, and source code, evaluate the strength of that evidence, then translate the strongest pattern into a small local fix, implementation path, or verification plan.

This is the code-focused edition of PavedPath. Do not broaden it into the future general-purpose PavedPath. It is for software engineering work: bugs, runtime errors, build/test/deploy failures, dependency issues, framework or API usage, integration blockers, implementation patterns, engineering tool selection, and open-source solution adaptation.

When to Use

• Runtime, build, test, deploy, package, SDK, API, dependency, framework, or integration errors.
• A feature implementation is blocked by an unclear edge case, missing usage pattern, version behavior, or uncertain API contract.
• A local issue resembles something that maintainers or other open-source users may have resolved in issues, PRs, examples, code, release notes, or discussions.
• The user asks whether GitHub or open-source projects have already solved a concrete engineering problem.
• Mature implementation examples or reusable projects would reduce uncertainty for one specific capability.
• The answer should compare suitable GitHub repositories and explain how to adapt one proven path locally.

Do not use PavedPath Code for copy edits, purely local refactors where the codebase already dictates the answer, non-code life decisions, self-media workflows, study methods, consumer purchasing decisions, or requests that explicitly forbid web/GitHub research. Do not inspect private repositories unless the user explicitly scopes and authorizes that access.

Default Workflow

1. Frame the local code problem first. Capture the goal, symptom, error signature, reproduction path, versions, runtime, dependency/framework names, recent changes, constraints, and attempted fixes. If a discoverable fact is missing, inspect local files/logs before asking.
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.
3. Evaluate subagent usefulness. Before substantial GitHub research, decide whether conditional subagent work would improve breadth, evidence quality, or review coverage. If not using subagents, state the reason briefly when reporting the search path.
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.
5. Find suitable GitHub projects when relevant. 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.
6. Search open-source evidence surfaces. Use issues, PRs, discussions, code, examples, release notes, and official project docs within relevant open-source repos. Repository search is required when a project itself may solve the problem.
7. Rank by problem fit first, with Stars as a maturity signal. A high-Star repository is a strong candidate for inspection, but maintainer-confirmed issues, merged PRs, released fixes, official examples, and exact matching code beat popular adjacent projects. Use research-rubric.md when ranking matters.
8. Deep-read the strongest projects and evidence. Use extraction-playbook.md to extract project basics, reusable surfaces, root cause or implementation pattern, version constraints, risks, adaptation boundaries, and verification steps.
9. Translate to local work with minimal adaptation. Preserve the proven workflow, API, configuration shape, or architecture where it fits. Adapt only the parts required by the user's local interfaces, configuration, data/auth model, deployment target, or language/runtime.
10. Verify before claiming success. Use tests, builds, reproduction commands, real requests, logs, browser checks, or manual inspection appropriate to the local problem.
11. If evidence is weak, say so. Do not stretch weak matches into a confident recommendation. Mark the recommendation as first-principles or local-only when open-source evidence is insufficient.

Subagent / Parallel Research Guidance

Subagents are conditional research aids, not a default requirement. The controller remains responsible for problem framing, scope control, evidence ranking, local adaptation, and final verification.

Use subagents when at least one of these applies:

• The problem spans 2+ independent ecosystems, frameworks, languages, tools, deployment surfaces, or GitHub communities.
• Repository discovery needs broad candidate coverage across multiple query families.
• Issue, PR, discussion, code, release, and example evidence can be split cleanly by project, version, or search surface.
• A final recommendation benefits from independent evidence review, risk review, or candidate rejection review.

Do not use subagents when any of these applies:

• The task is a narrow error with one obvious package, repository, API, or maintainer surface.
• Local repository context, logs, config, or reproduction details must be understood before external research can be scoped safely.
• GitHub rate limits, authorization boundaries, private repositories, secrets, production data, or sensitive logs would make delegation risky.
• Subagents would mostly duplicate the same searches or edit the same local files.

When using subagents, the controller must:

• 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 unless a separate implementation phase has a narrow allowed write scope.
• Merge and deduplicate results before ranking; do not count repeated reports of the same issue, PR, code path, or repository as independent evidence.
• Directly verify the strongest claims with gh, source reads, tests, logs, real requests, or official docs before finalizing.

GitHub CLI First

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. Do not add or rely on bundled search scripts for this skill.

Use these short command templates as starting points, then adjust the query, repo, fields, and limits to the local problem:

gh search repos "<query>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
gh search issues "<query>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search prs "<query>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search code "<query>" --repo owner/repo --limit 10 --json path,url,repository,sha
gh repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
gh api -X GET search/repositories -f q='<query> archived:false' -f sort=stars -f order=desc

Only run gh auth status when a command fails with 403, 429, a private repository authorization error, or an explicit gh not-authenticated message. If GitHub returns 403/429, 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.