/can-i-help

name: can-i-help
description: 'Use when the user asks "where to help", "contribution opportunities", or "find a good first issue". Returns data-backed first steps. Not for PR review queues: use gh-review-requests.'

Can I help

Contract

| Field | Bound contract | |---|---| | Trigger | The user asks "where can I help", "what can I contribute", "find a good first issue", or "what should I work on". | | Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. | | Side effect | None; ranked recommendations only. | | Done | Two to five evidenced recommendations with what, why, location, and first step, each based on a read source range and carrying a certainty label. |

Inputs

• Target repository (optional): defaults to the current working directory. If the user supplies a path, use it.
• Developer interest (collected during execution, not supplied upfront): a single-select choice that routes signal ranking.

Procedure

1. **Bound scope.** If the user already named an exact task or issue, stop: solve that task instead. If the request is pure project orientation with no contribution decision, produce orientation, not recommendations. If the repo cannot be read locally and no public issue tracker is available, report what is missing and stop. **Done when:** scope is bounded to contribution recommendations, or the request is redirected to the named task or orientation.

2. **Resolve target and collect base context.** Default target is the current repo unless the user supplied a path. Capture the project shape before ranking:

• Manifests: `fd '^(package.json|pyproject.toml|Cargo.toml|go.mod|pom.xml|build.gradle|deno.json|bun.lockb|pnpm-lock.yaml|requirements.txt)$' <repo>`.
• Top-level structure: `fd --max-depth 3 --type f <repo>`; exclude generated/vendor directories.
• README / contributing docs: `fd '^(README|CONTRIBUTING|DEVELOPMENT|HACKING)(\..*)?$' <repo>` then read the relevant file ranges.
• Test roots: `fd '(^test$|^tests$|__tests__|spec$|\.test\.|\.spec\.)' <repo>`.
• Build/test commands: derive from manifest scripts, Makefile targets, CI config, or existing docs; mark certainty MEDIUM unless a command is explicitly declared. **Done when:** the project shape and active local modifications are recorded.

3. **Collect contribution signals with native recipes.** Prefer indexed codegraph when available; otherwise use `ast-grep`, `rg`, `fd`, and git history. Keep every signal as `{kind, file, line?, metric, confidence, evidence}`. Missing `kind`, `file` for file-backed work, or `evidence` downgrades the candidate to LOW. **Done when:** every collected signal has kind, file where applicable, evidence, and confidence.

• Good-first areas: low blast radius, clear adjacent patterns, nearby tests, recent maintainer activity, low bug density. Fallback: count importers with `rg -n 'from .*/<module>|require\(.*/<module>|use .*<module>|import .*<module>'` and prefer files with few dependents plus visible neighboring tests.
• Test gaps: hot source files with no co-changing test file. `git --no-pager log --since='180 days ago' --name-only --format='commit:%H' -- <src-paths>`; rank source files by touches, then subtract files whose commits include a matching `test|tests|spec|__tests__` path. HIGH when source churn ≥5 and zero matching test co-change; MEDIUM when no test root exists but naming conventions are unclear.
• Doc drift: docs with zero or weak code coupling, stale inline identifiers, or examples importing paths that no longer exist. `git --no-pager log --since='365 days ago' --name-only --format='commit:%H' -- docs README* CONTRIBUTING*`; compute doc commits with no source files. Extract backticked identifiers/import paths from docs, check via codegraph search, else `rg -n '<identifier-or-path>' <repo>`. HIGH for broken import/path; MEDIUM for zero code coupling over the window.
• Bugspots: files repeatedly touched by fix commits. `git --no-pager log --since='365 days ago' --regexp-ignore-case --grep='fix|bug|regression|crash|panic|race|leak|broken' --name-only --format='commit:%H' -- <repo>`; bug-fix rate = `fix_touches / max(total_touches, 1)`. HIGH when fix_touches ≥3 and rate ≥0.25; MEDIUM when only one threshold holds.
• Open issues: `gh issue list --state open --limit 15 --json number,title,labels`. Route labels: `bug`/`regression`/`crash` → bugs; `good first issue`/`help wanted` → newcomer; `documentation`/`docs` → docs; `test`/`testing`/`coverage` → tests; `cleanup`/`refactor`/`chore` → cleanup only after repo verification. If `gh` fails, mark issue signal unavailable and continue.
• Slop-deletion candidates: commented-out code, orphan exports, passthrough wrappers, and always-true/always-false conditions. Use AST where possible; never promise zero-behavior cleanup until the slop verification gate (step 8) passes.

4. **Ask the developer's interest, mandatory and first, before recommendations.** Present a single-select with exactly one Recommended option. Do this even if signals already look obvious. **Done when:** the developer selects one interest. Prompt: `What kind of contribution do you want to make?` Options:

• `New to the stack`: Recommended when good-first areas or cleanup candidates exist.
• `Experienced`: hard problems, bugspots, architecture-adjacent issues.
• `Want to write tests`: test gaps and bugspot overlap.
• `Want to fix bugs`: bug-labelled issues, bugspots, suspicious conditions.
• `Want to improve docs`: stale references, doc drift, documentation issues.
• `Want quick cleanup`: verified deletion-only or tightly-contained cleanup.

5. **Route interest to signals.** Lead with the strongest non-empty primary signal for the chosen interest; skip empty subsections with one sentence, not a filler apology. If the chosen interest has no supporting signal, name which signal was empty and pivot to the nearest adjacent interest with data. **Done when:** the select