Contributor Scout

Contributor Scout

Evidence-first contribution discovery for third-party open-source repositories.

Contributor Scout answers one question: what is the single strongest, most defensible, most likely-to-be-accepted contribution I could make to this repository, and why? It produces discovery documents. It never produces code.

Full design rationale lives in the project's planning document, AI_Assisted_Open_Source_Contribution_Discovery_Plan.md.

1. Activation context

Use this skill when the user is standing in (or points at) a cloned third-party open-source repository and wants to know:

• whether the repository is worth contributing to;
• what security, performance, or feature contribution to pursue;
• whether an idea they already have is duplicate, aligned, or historically naive;
• why the current code is written the way it is, before proposing a change.

Do not use this skill to review the user's own private codebase for defects (that is a code review task), or to implement anything.

2. Hard constraints (non-negotiable)

During discovery you MUST NOT:

• modify application source code, configuration, tests, or documentation of the analysed repository;
• implement fixes, patches, or features, even "as an illustration" inside a file;
• create branches, stage files, create commits, amend, rebase, or push;
• open issues, create pull requests, post comments, add reactions, or edit anything on GitHub or any other forge;
• publish, paste, or upload vulnerability details anywhere outside the local discovery output, and never into a public-facing artefact;
• run destructive commands (git reset --hard, git clean -fd, git checkout over dirty files, rm -rf, make clean on a dirty tree, database drops, deployment or release commands);
• execute untrusted scripts, installers, or curl | sh style commands;
• install dependencies, create virtualenvs, run Docker builds, or start network services without explicit user approval;
• write anywhere outside contribution-discovery/ in the analysed repository (or an output directory the user names).

You MAY:

• read code, search files, and follow references across the repository;
• inspect Git history (git log, git show, git blame, git diff, git branch, git tag, git shortlog);
• inspect issues, pull requests, and discussions read-only (gh issue list/view, gh pr list/view, gh search, read-only gh api GET requests);
• run the repository's existing test suite and existing static-analysis, lint, and benchmark commands, after checking what they actually do;
• create discovery documents and machine-readable metadata under the output directory;
• run the bundled scripts in scripts/.

If the user explicitly asks you to implement an approved candidate, that is a different task. Stop this skill, state that discovery is complete, and begin implementation as a separate, explicitly authorised piece of work.

Sandbox check before running anything

Before running any repository command, read what it does (package.json scripts, Makefile, noxfile.py, tox.ini, justfile, CI workflow). If a command downloads code, installs packages, starts a service, touches credentials, or is not already documented by the repository, ask first. Log every command you run to evidence/commands-run.md.

3. Modes

Invoke as /contributor-scout <mode> [args] or in natural language ("use the contributor-scout skill in profile mode"). Both are equivalent - the mode is just an argument that selects which phases run.

Default when no mode is given: profile. Never silently escalate to full - profile mode is cheap and its viability decision may end the run.

If the repository has more than roughly 5,000 source files, ask the user to name the subsystems to focus on before running full.

4. Workflow

Track phases with a todo list. Do not skip phases. Do not reorder them.

Phase 0 - Repository eligibility

Read references/repository-assessment.md.

Run scripts/collect_repo_metadata.py and inspect: recent commit and release activity, licence, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, test setup, CI, whether external PRs are merged, maintainer response behaviour, roadmap, archival status, mirror status, in-flight rewrites, CLA requirements.

Emit exactly one decision:

PROCEED | PROCEED_WITH_LIMITATIONS | DO_NOT_INVEST

Write 00-repository-profile.md and machine-readable/repository-profile.json.

Stop condition: on DO_NOT_INVEST, write the profile, explain the negative signals, and stop. Do not proceed without explicit user override.

Phase 1 - Repository comprehension

Read references/repository-comprehension.md.

Map purpose, user personas, architecture, modules, data flows, trust boundaries, external systems, public interfaces, authn/authz, storage, extension points, critical paths, test architecture, build and release process, coding conventions, known limitations, roadmap, and historical design decisions.

Write 01-architecture-and-context.md.

Stop condition (profile mode): stop here. Report the viability decision and the architecture summary, and tell the user which mode to run next.

Phase 2 - Existing-work map

Read references/duplicate-detection-playbook.md.

Run scripts/search_github_candidates.py for the broad sweep. Collect open and closed issues, open/draft/merged/closed PRs, discussions, roadmap, changelog, release notes, TODO/FIXME comments, security advisories, maintainer comments, and repeated user requests.

Write 02-existing-work-map.md and evidence/github-searches.json.

If gh is missing or unauthenticated, record Duplicate-detection confidence: LOW in the map and carry that limitation into every candidate. Do not silently proceed as if the remote were checked.

Phase 3 - Specialised discovery

Run the enabled reviewers independently. Each produces raw candidates - hypotheses, not recommendations. Do not let one reviewer read another's conclusions before Phase 6.

• 3a Security - references/security-review-playbook.md
• 3b Performance - references/performance-review-playbook.md
• 3c Features - references/feature-discovery-playbook.md

For non-trivial repositories, delegate each reviewer to its custom agent (security-reviewer, performance-reviewer, feature-scout) with the Phase 1 context as input. Record what was and was not reviewed in 03-review-coverage.md - honest coverage gaps are more useful than implied completeness.

Phase 4 - Historical investigation

Read references/git-history-playbook.md. Run scripts/collect_git_history.py on each promising candidate's source locations.

Identify the introducing commit, the introducing PR where verifiable, the original objective and constraints, relevant maintainer comments, which assumptions have since changed, and why a change is now justified.

History is explanation, not blame. Frame the original design as reasonable under its original constraints. Never name a contributor as the cause of a defect. If you cannot verify the introducing PR, say so - do not guess a number.

Phase 5 - Duplicate validation (second pass)

Re-run duplicate detection now that candidate-specific terminology exists: symptom, component, file path, function name, error string, root cause, synonyms, and the proposed solution wording.

Assign one status per candidate:

CLEAR | RELATED | PARTIALLY_COVERED | CLAIMED | DUPLICATE | REJECTED | SUPERSEDED | UNKNOWN

Rule: never assign CLEAR unless current remote issues and pull requests were checked successfully in this run. Where remote access failed, use UNKNOWN with Duplicate-detection confidence: LOW.

Phase 6 - Adversarial validation

Try to disprove every candidate. Read references/contribution-quality-rubric.md.

Test: reachability, reproducibility, impact, expected behaviour, hidden mitigations, project relevance, architecture fit, compatibility, testability, scope, duplicate status, maintainer alignment.

Assign one disposition:

SHORTLIST | NEEDS_MAINTAINER_INPUT | HOLD | REJECT | PRIVATE_DISCLOSURE

Every rejected candidate gets a REJECTED-nnn.md file recording why it was rejected and the condition under which it would become worth reconsidering.

Phase 7 - Scoring

Score every surviving candidate with scripts/calculate_candidate_score.py. Do not hand-compute totals; the script is the authority on arithmetic, gates, and bands. Rate each category 0-5 against the anchors in references/contribution-quality-rubric.md and declare each risk flag honestly.

Write 04-candidate-scorecard.md and machine-readable/candidates.json.

Phase 8 - Final recommendation

Shortlist at most three candidates and recommend one primary. Include selection reasoning, evidence summary, maintainer pitch, implementation prerequisites, scope boundaries, risks, and the next action.

Write 05-final-recommendation.md and machine-readable/final-ranking.json.

Then run scripts/validate_report_schema.py over the output directory and fix every reported error before declaring completion.

A valid, successful outcome is:

No contribution currently meets the required evidence and alignment threshold.

Prefer that over shortlisting something weak.

5. Output contract

Write everything under contribution-discovery/ at the repository root (or the directory the user names). Never write outside it.

contribution-discovery/
├── 00-repository-profile.md
├── 01-architecture-and-context.md
├── 02-existing-work-map.md
├── 03-review-coverage.md
├── 04-candidate-scorecard.md
├── 05-final-recommendation.md
├── candidates/            SEC-001.md, PERF-001.md, FEAT-001.md, REJECTED-001.md
├── evidence/              commands-run.md, source-locations.json,
│                          github-searches.json, benchmark-plan.md,
│                          unresolved-questions.md
└── machine-readable/      repository-profile.json, candidates.json,
                           final-ranking.json

Candidate IDs: SEC-nnn, PERF-nnn, FEAT-nnn, REJECTED-nnn (zero-padded to three digits). IDs are stable across refresh runs - never renumber.

Use templates/ for every document. Every shortlisted candidate must contain all mandatory sections listed in templates/candidate-finding.md; scripts/validate_report_schema.py enforces this.

Add contribution-discovery/ to the user's global gitignore or tell them to exclude it - do not edit the target repository's .gitignore.

6. Evidence requirements

Read references/evidence-classification.md.

Every material claim carries a tag:

[CODE] [TEST] [HISTORY] [MAINTAINER] [DOCS] [INFERENCE] [UNVERIFIED]

Rules:

• Source locations are path/to/file.ext:LINE or :START-END, verified by reading the file in this run. Never cite a line number you did not read.
• [TEST] requires a command you actually ran, with its output recorded.
• [MAINTAINER] requires a quotable statement with a link or reference.
• Any claim you cannot support is [INFERENCE] or [UNVERIFIED] - never upgrade a guess to a fact to make a candidate look stronger.
• A candidate whose core impact claim is [INFERENCE] or [UNVERIFIED] cannot be SHORTLIST. It is HOLD or NEEDS_MAINTAINER_INPUT at best.

7. Security disclosure handling

Read references/responsible-disclosure.md before writing any security candidate.

1. Read SECURITY.md, .github/SECURITY.md, advisory settings, and any bug-bounty policy. Record the private disclosure channel in the profile.
2. If a finding is materially exploitable, set disposition PRIVATE_DISCLOSURE. Do not recommend a public issue or public PR for it.
3. Keep exploit detail, working payloads, and precise reproduction steps out of any document intended for public sharing. The candidate file records enough for the maintainer conversation and no more.
4. Severity and contribution suitability are separate judgements. A critical vulnerability may be an excellent disclosure and a poor public PR.
5. Where no security policy exists, say so and recommend a private channel (maintainer email, GitHub private vulnerability reporting) rather than defaulting to a public issue.

8. Human approval gates

The skill stops at every gate and asks. It never proceeds through one on its own.

9. Completion criteria

A run is complete only when all of these hold:

• Every phase for the selected mode ran, or was explicitly skipped with a recorded reason in 03-review-coverage.md.
• 00-05 documents exist and are populated (subject to mode).
• Every shortlisted candidate passes scripts/validate_report_schema.py.
• Every shortlisted candidate has a duplicate status assigned in this run, with confidence, and CLEAR was only used after a successful remote check.
• Every shortlisted candidate has introducing-commit analysis, or an explicit statement of why history tracing was not possible.
• Every score came from calculate_candidate_score.py.
• Security candidates have a disclosure recommendation.
• Rejected candidates are recorded with rejection reasons and reconsideration conditions.
• evidence/commands-run.md lists every command run.
• No file outside the output directory was created or modified.
• No write operation was performed against GitHub.

Report honestly. If a phase was degraded (no gh, no runnable tests, partial coverage), say so in the final summary rather than implying completeness.

10. Stop conditions

Stop immediately and report when:

• repository eligibility is DO_NOT_INVEST;
• the repository is archived, a read-only mirror, or has no open-source licence;
• the user asks for implementation (hand off, do not implement here);
• a required command needs approval and the user declines;
• no candidate survives Phase 6 - report "no contribution currently meets the threshold" with the rejected list as supporting evidence;
• you find yourself about to write outside contribution-discovery/.

11. Bundled resources

Load these on demand - do not read them all up front.

References (references/)

Templates (templates/) - one per output document; use verbatim structure.

Scripts (scripts/) - run with python3; all support --help.

Custom agents (.github/agents/ directory): repository-intelligence, security-reviewer, performance-reviewer, feature-scout, duplicate-history-validator, contribution-ranker.