contributor-experience

Files (14)

• SKILL.md
• ci.yml · assets/contrib-sample/.github/workflows/
• CODEOWNERS · assets/contrib-sample/
• CONTRIBUTING.md · assets/contrib-sample/
• ISSUE_TEMPLATE.md · assets/contrib-sample/
• Makefile · assets/contrib-sample/
• contributor-report-template.md · assets/
• check-parity.md · references/
• contributor-journey.md · references/
• funnel-fixes.md · references/
• guidance-files.md · references/
• review-experience.md · references/
• standards.md · references/
• check_contributor_funnel.py · scripts/

SKILL.md (first lines)

# Contributor Experience Audit and Repair

## Mission

The first meaningful contribution is the product's open-source funnel. Every future contributor, reviewer, and maintainer enters through it; a blocked funnel caps the community at the size of the founding team.

Treat the fork-to-merge path as a product with its own SLA. Measure it, find the friction, and repair the repository so a brand-new contributor with no project-specific knowledge goes from fork to a PR-ready change quickly and to a merged change predictably.

Fix the repository, do not document around it. When setup, checks, or guidance make contribution hard, repair the automation and the files instead of adding longer READMEs.

The local setup itself — toolchain, dependencies, services, fixtures, hot reload — belongs to the `local-development` skill if available. This skill audits the funnel around that setup; it does not duplicate it. For whole-product journey measurement use `developer-experience-auditor` if available, and for designing onboarding journeys use `developer-onboarding` if available.

Read `references/contributor-journey.md` when walking the fork-to-merge path step by step.

Read `references/guidance-files.md` when auditing CONTRIBUTING, CODEOWNERS, issue/PR templates, good-first-issue labeling, or DCO/CLA.

Read `references/check-parity.md` when verifying that local checks match CI.

Read `references/review-experience.md` when measuring review responsiveness and first-time-contributor friendliness.

Read `references/funnel-fixes.md` when repairing funnel defects found by the audit.

Read `references/standards.md` for the canonical thresholds, severity vocabulary, and release gates.

## Hard target: first contribution within FIRST_CONTRIBUTION_TARGET_MIN

A brand-new contributor with no prior project knowledge must go from fork to a first PR-ready change within `FIRST_CONTRIBUTION_TARGET_MIN`, using only committed instructions and automation.

This is a target, not a hard gate: landing inside the target is the goal, exceeding it is a PASS WITH DEBT signal, and exceeding it substantially is a P2 defect per `references/standards.md`.

The timer starts at the fork and stops when the change is PR-ready: the change is made, local checks pass, and CI runs the same checks. The contributor journey after PR-ready — review and merge — is measured separately and reported per stage.

Do not move repository friction into "contributor prerequisites". A requirement the repo cannot verify is a defect, not a prerequisite.

The repo's contribution guidance must make the journey walkable from a clean clone using only committed instructions. Any step that lives only in a maintainer's memory is a `NON_REPRODUCIBLE_BUILD` gate failure.

## Contributor experience workflow

### 1. Audit the contributor journey

Read `references/contributor-journey.md`.

Walk each stage of the journey — fork, clone, build, test, find issue, change, checks, PR, review, merge — against the target repository exactly as a first-time contributor would.

Verify:

- build and test succeed from a clean clone using only committed instructions
- each stage's friction is recorded with per-stage timing and an evidence label
- the contributor can verify a change locally with the same checks CI runs
- fixtures or seed data exist where the tests or examples need them

Do not average stages. Report per stage; the bottleneck is the longest stage, not the mean. If the local setup fails a clean-clone check, hand the setup repair to the `local-development` skill if available before continuing.

### 2. Audit repo guidance files

Read `references/guidance-files.md`.

Run `scripts/check_contributor_funnel.py <repo>` as a first-pass inventory signal. The script is heuristic; verify each finding in the files themselves.

Verify:

- CONTRIBUTING.md exists and answers how to run tests, how to make a change, and what review expects
- CODEOWNERS covers the change paths and is current
- issue and PR templates exist, are current, and match the repo's actual workflow
- DCO/CLA is stated, enforceable, and its bot check is enabled
- the good-first-issue labeling procedure is documented

Never accept a CONTRIBUTING.md that points at tribal knowledge or an unreachable setup.

### 3. Audit issue discoverability

Read `references/guidance-files.md` for the labeling procedure.

Verify:

- good-first-issue issues are small, self-contained, and free of internal jargon
- each labeled issue has a clear acceptance criterion
- labeled issues are fresh, not stale triage backlog
- the label is discoverable from the README or CONTRIBUTING

Do not count a label as a signal when the underlying issues are not first-timer-sized.

### 4. Audit check parity (local make test vs CI)

Read `references/check-parity.md`.

Verify:

- the canonical local check command exists (Makefile `test` target or package.json `test` script) and runs green from a clean clone
- CI runs the same command, the same versions, and the same failure conditions
- no check passes locally and fails in CI, or vice versa

Do not accept "CI is green" as evidence that the contributor's local check is green. Drift between the two is a parity defect, not an environment quirk.

### 5. Audit review responsiveness

Read `references/review-experience.md`.

Verify:

- review expectations are documented: who reviews, how fast, what happens on disagreement
- first-response time and time-to-merge are measured on real PRs with evidence labels
- first-time contributors get a constructive, welcoming review
- there is a path from first contribution to reviewer or maintainer

Do not label a repo "responsive" from maintainer claims. Sample actual PR history.

### 6. Fix the funnel

Read `references/funnel-fixes.md`.

Prioritize by severity vocabulary from `references/standards.md`. Fix in this order:

1. check parity — a contributor who cannot verify their change locally is blocked at the widest point
2. guidance and templates — a missing or wrong CONTRIBUTING costs every contributor
3. discoverability — small first issues unblock the first contribution specifically
4. review responsiveness — merge latency caps the funnel's throughput

Implement each fix with an acceptance test: the repair is done when a fresh walk of the stage passes. Never claim a fix without re-running the affected journey step.

From devarispbrown/devex-skills, MIT.

More from devarispbrown/devex-skills