oss-evaluate-repo

# Evaluate Repo

Is this repo worth your time? Not every open source project deserves months of contribution effort. This skill evaluates project health, governance, community dynamics, and trajectory — so you invest in repos that will value your work and still exist in a year.

## Purpose

Contributing to OSS is an investment. A single meaningful PR takes 10-40 hours including learning the codebase. Before investing that time, you should know: Is this project actively maintained? Is the community healthy? Will your contributions be reviewed? Could the project be abandoned next month? This skill answers those questions with evidence, not vibes.

## When to Use

- Deciding whether to invest time in a specific OSS project
- Choosing between multiple repos to contribute to
- Evaluating a project before committing to a GSoC proposal
- **NOT** for checking if a repo accepts external contributions — `oss-find-issue` does that
- **NOT** for evaluating code quality — `oss-explore-repo` does that
- **NOT** for repos you're already contributing to — too late, you're invested

## Prerequisites

- A repo URL or name to evaluate
- `gh` CLI authenticated
- Clear goals for why you want to contribute (learning, career, community)

## Process

### 1. Check vital signs

These are binary health checks — if any fail, the repo is likely not worth investing in.

```bash
# Basic repo info
gh api repos/{owner}/{repo} --jq '{
  stars: .stargazers_count,
  forks: .forks_count,
  open_issues: .open_issues_count,
  archived: .archived,
  license: .license.spdx_id,
  created: .created_at,
  updated: .pushed_at,
  default_branch: .default_branch
}'

# Recent commit activity
git log --oneline -20 --since="6 months ago" 2>/dev/null || \
  gh api repos/{owner}/{repo}/commits --jq '.[0:10] | .[] | "\(.commit.author.date[:10]) \(.commit.message | split("\n")[0])"'

# Is the repo archived or in maintenance mode?
gh api repos/{owner}/{repo} --jq '.archived'
```

**Kill signals** (stop evaluation if any are true):
- Archived or read-only
- No commits in 6+ months
- README says "no longer maintained" or "looking for maintainers"
- License is missing or incompatible with your needs

### 2. Assess governance and bus factor

Who runs this project, and what happens if they leave?

```bash
# Top contributors (bus factor check)
gh api repos/{owner}/{repo}/contributors --jq '.[0:10] | .[] | "\(.contributions)\t\(.login)"'

# Recent committers (who's active NOW, not historically)
gh api repos/{owner}/{repo}/commits --jq '[.[0:50] | .[].author.login // "unknown"] | sort | group_by(.) | map({user: .[0], commits: length}) | sort_by(-.commits) | .[0:5] | .[] | "\(.commits)\t\(.user)"'

# Check if it's an org or personal project
gh api repos/{owner}/{repo} --jq '.owner.type'
```

Evaluate:
- **Bus factor**: How many people have committed in the last 3 months? If it's 1, the project dies if they stop.
- **Org vs personal**: Org-backed projects are more sustainable. Personal projects depend on one person's motivation.
- **Corporate backing**: Check if contributors have @company emails or if the org is a company. Corporate-backed OSS has resources but may shift priorities.
- **Governance model**: Is there a GOVERNANCE.md? A code of conduct? A clear decision-making process?

### 3. Evaluate community health

A healthy community means your contributions get reviewed, your questions get answered, and conflicts get resolved.

```bash
# Issue responsiveness — how quickly do issues get responses?
gh issue list -R {owner}/{repo} --state closed --limit 20 --json number,createdAt,closedAt,comments \
  --jq '.[] | {number, created: .createdAt[:10], closed: .closedAt[:10], comments: .comments}'

# PR review turnaround
gh pr list -R {owner}/{repo} --state merged --limit 20 --json number,createdAt,mergedAt,reviews \
  --jq '.[] | {number, created: .createdAt[:10], merged: .mergedAt[:10], reviews: (.reviews | length)}'

# Check for toxic interactions (look at recent closed issues/PRs)
gh issue list -R {owner}/{repo} --state closed --limit 5 --json number,comments \
  --jq '.[].number' | while read n; do
    echo "=== Issue #$n ==="
    gh issue view $n -R {owner}/{repo} --json comments --jq '.comments[-3:] | .[].body' | head -20
  done
```

**Healthy signals**:
- Issues get responses within a week
- PRs get reviewed within 2 weeks
- Maintainers are polite and constructive
- External contributors' PRs actually get merged
- Disagreements are resolved respectfully

**Unhealthy signals**:
- Issues and PRs sit for months without response
- Maintainer tone is dismissive or aggressive
- External PRs get closed without explanation
- Community discussions are toxic or absent
- "Drive-by" maintainer activity (once a month, closes 20 issues, disappears)

### 4. Check release cadence and stability

```bash
# Recent releases
gh release list -R {owner}/{repo} --limit 10

# Release frequency
gh release list -R {owner}/{repo} --limit 10 --json tagName,publishedAt \
  --jq '.[] | "\(.publishedAt[:10])\t\(.tagName)"'
```

Evaluate:
- **Regular releases**: Monthly or quarterly releases signal active development
- **Stale releases**: Last release 2+ years ago means your contributions won't reach users
- **Breaking changes**: Frequent major versions suggest instability
- **Changelog quality**: Detailed changelogs signal mature project management

### 5. Evaluate CI and development practices

```bash
# CI configuration
ls .github/workflows/ 2>/dev/null
cat .github/workflows/ci.yml 2>/dev/null | head -30

# Code quality tools
ls .eslintrc* .prettierrc* pyproject.toml rustfmt.toml .editorconfig 2>/dev/null

# Test infrastructure
find . -name "*test*" -type d -maxdepth 3 2>/dev/null | head -10
```

**Mature project signals**:
- CI runs on PRs (not just main)
- Linting and formatting enforced
- Test suite exists and is maintained
- Code review is required (branch protection)

### 6. Thinking gate — user articulates the decision

Present all findings in a structured summary and as