/pavedpath-code

name: pavedpath-code
description: PavedPath Code is the code-focused edition of PavedPath. It helps agents solve software engineering problems by finding proven implementation paths from GitHub repositories, issues, pull requests, discussions, code examples, release notes, and open-source evidence.

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](references/research-rubric.md) when ranking matters. 8. **Deep-read the strongest projects and evidence.** Use [extraction-playbook.md](references/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 tas