Oss Find Real Issues

Find Real Issues

Don't wait for someone to file an issue. find real problems in the code. This skill analyzes a codebase for actual issues that maintainers would appreciate being fixed: missing tests, inconsistent patterns, silent failures, documentation gaps. You evaluate whether they're worth filing. the LLM just finds them.

Purpose

The best contributions aren't always in the issue tracker. Experienced contributors earn maintainer trust by finding and fixing problems nobody asked about. but that everyone benefits from. This skill teaches you to read code critically, spot patterns that are off, and evaluate whether a fix would be welcome.

Prerequisites

• A repo cloned locally
• Basic understanding of the codebase (from oss-prep-to-contribute or your own exploration)
• Check that the repo accepts unsolicited PRs (some don't. verify in CONTRIBUTING.md)

Process

1. Check if unsolicited contributions are welcome

Before analyzing anything:

# Read contribution guidelines
gh api repos/{owner}/{repo}/contents/CONTRIBUTING.md --jq '.content' | base64 -d 2>/dev/null

# Check if unsolicited PRs have been merged before
gh pr list -R {owner}/{repo} --state merged --limit 20 \
  --json title,labels,authorAssociation | \
  jq '[.[] | select(.authorAssociation != "MEMBER" and .authorAssociation != "OWNER")]'

Look for:

• "Please file an issue before submitting a PR": if present, you should file an issue first, not just submit a fix
• "We welcome contributions": green light
• No external PRs merged. yellow flag, ask in their communication channel first

Inform the user about the repo's stance on unsolicited contributions.

2. Systematic code analysis

Use Explore agents to analyze the codebase across multiple dimensions. For each dimension, look for concrete, specific problems. not vague "could be better" observations.

Dimension 1: Test coverage gaps

# Find source files without corresponding test files
find src/ lib/ -name "*.{ts,py,go,rs}" | while read f; do
  test_file=$(echo "$f" | sed 's/src/test/' | sed 's/\.ts/.test.ts/' | sed 's/\.py/test_&/')
  [ ! -f "$test_file" ] && echo "No test: $f"
done

# Find exported functions that aren't tested
# {language-specific analysis}

Dimension 2: Error handling gaps

# Find try/catch or error handling patterns and look for inconsistencies
grep -rn "catch\|except\|Error\|panic\|unwrap" src/ --include="*.ts" --include="*.py" --include="*.go" --include="*.rs" | head -30

# Find functions that call external services/APIs without error handling
# {trace external calls}

Dimension 3: Inconsistent patterns

# Compare naming conventions across modules
grep -rn "function\|def \|fn \|func " src/ --include="*.ts" --include="*.py" --include="*.go" --include="*.rs" | head -30
# Look for: camelCase vs snake_case mixing, inconsistent prefixes, different error types for the same kind of failure

# Find multiple approaches to the same problem
# Example: some modules use callbacks, others use promises, others use async/await
grep -rn "callback\|\.then(\|async " src/ --include="*.ts" --include="*.py" --include="*.go" --include="*.rs" | head -20

# Check for deprecated API usage
grep -rn "deprecated\|@deprecated\|DEPRECATED" src/ --include="*.ts" --include="*.py" --include="*.go" --include="*.rs"

Dimension 4: Documentation gaps

# Find README references to files that don't exist
grep -oP '\[.*?\]\(((?!http).*?)\)' README.md 2>/dev/null | while read link; do
  file=$(echo "$link" | grep -oP '\(.*?\)' | tr -d '()')
  [ ! -f "$file" ] && echo "Broken link: $link -> $file"
done

# Check if setup/install commands in README actually work
# Read the "Getting Started" section and verify each command

# Find public functions/classes without docstrings (Python example)
grep -rn "def \|class " src/ --include="*.py" -A1 | grep -B1 -v '"""' | grep "def \|class "

Dimension 5: Dependency issues

# Language-specific vulnerability checks
npm audit 2>/dev/null          # Node.js
pip audit 2>/dev/null          # Python (requires pip-audit)
cargo audit 2>/dev/null        # Rust
go list -m -json all 2>/dev/null | grep -i "deprecated"  # Go

3. Filter for actionable findings

Not every code smell is worth filing. Filter each finding:

4. Present findings to the user

For each finding, present:

## Finding #{n}: {one-line summary}

**Category**: {test gap / error handling / inconsistency / docs / security / dependency}
**Severity**: {high. could cause bugs or security issues / medium. code quality / low. cosmetic}
**Location**: `{file}:{line}` 
**What's wrong**: {specific description with code reference}
**Impact**: {what could go wrong because of this}
**Suggested approach**: {high-level. not a code fix, just the direction}
**Would a PR be welcome?**: {yes. clearly a bug / maybe. discuss first / probably not. too opinionated}

5. Thinking gate: user evaluates each finding

For each finding, ask the user:

"Look at finding #{n}. I showed you the location and impact above.

1. Do you agree this is a real problem? (Look at the code at the location I cited)
2. If you were a maintainer, would you merge a PR fixing this?
3. What could go wrong if this stays unfixed? (Check the 'Impact' section above)"

This is the most important part. The skill isn't just about finding issues. it's about teaching the user to evaluate code critically. Their judgment matters more than the LLM's analysis.

If the user says "yes, fix it" without articulating WHY:

"Before we proceed. explain why this is a problem. What could go wrong if it stays as-is? A maintainer will ask this in the PR review."

If the user disagrees with a finding:

"Good. that's a valid call. Can you explain why you think it's not an issue? Understanding why something ISN'T a problem is just as valuable."

6. Verify the finding before it becomes an issue

A finding the user believes is not a finding the repo will accept. Filing a report that turns out to be intended behaviour costs the user credibility that takes months to rebuild, and it costs a maintainer the time to explain it. Three checks, all of them, on every finding. Any one failing kills the report.

Reproduce it. Write the smallest thing that shows the behaviour: a failing test, a script, a command with its output. A finding that cannot be demonstrated is a guess about code the user has read, not a problem the repo has.

Search prior art, closed as well as open. Closed is where the answer usually is, because somebody already asked and a maintainer already explained why it is this way.

gh search issues --repo {owner}/{repo} --state open   "{keyword}" --limit 20
gh search issues --repo {owner}/{repo} --state closed "{keyword}" --limit 20
gh search prs    --repo {owner}/{repo} --state closed "{keyword}" --limit 20

Search the symbol, the error text, and the plain-language description separately. They surface different threads. A merged PR in those results means it is already fixed on the default branch and the user is reading a release.

Check whether it is deliberate. The most common false positive is behaviour a test already asserts, which means somebody decided it on purpose:

# Does a test pin the behaviour the user is about to call a bug?
grep -rn "{symbol}" test/ tests/ spec/ __tests__/ 2>/dev/null

# Snapshot and inline-snapshot tests are the ones that catch people out
grep -rln "snapshot\|golden\|approved\|__snapshots__" test/ tests/ 2>/dev/null

# Was it written this way on purpose, and does the commit say why?
git log -S "{the exact symbol or line}" --oneline -- {path}

If a test asserts the current behaviour, it is a design decision until a maintainer says otherwise. The user may still disagree with it, but the report is then "I think this decision is wrong, here is why", which is a different conversation from "this is broken", and it gets a different reception.

"Before we file this, show me:

1. The reproduction. What exactly did you run, and what did you see?
2. What did the closed issues and PRs say about it?
3. Is there a test asserting the current behaviour? If yes, why is the decision wrong?"

A finding that cannot answer all three does not get filed. Drop it, or go back to step 2 and gather what is missing.

7. Fetch issue templates

Before filing, check if the repo has issue templates:

# Check for issue template directory (multiple templates)
gh api "repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE" \
  --jq '[.[] | select(.name != "config.yml") | .name]' 2>/dev/null

# Check for single-file issue template
gh api "repos/{owner}/{repo}/contents/ISSUE_TEMPLATE.md" --jq '.content' 2>/dev/null | base64 -d 2>/dev/null
gh api "repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE.md" --jq '.content' 2>/dev/null | base64 -d 2>/dev/null

If a template directory exists: fetch each template file (skip config.yml: it's not a template). Templates can be .md (with YAML frontmatter) or .yml (issue forms). For .md templates, parse the YAML frontmatter (name, description, labels). For .yml issue forms, parse the top-level name, description, and labels fields directly. Present the available templates:

Available issue templates:
1. Bug Report: Report a bug (labels: bug)
2. Feature Request: Suggest an enhancement (labels: enhancement)
3. Documentation: Report a docs issue (labels: documentation)

Ask the user: "Which template matches the issue you're filing?" Fetch the selected template and enforce its structure.

If a single template exists: use it as the required format.

If no templates exist: use the freeform issue format below.

8. File issues or proceed to fix

For findings the user validates:

Option A: File an issue first (recommended for medium+ changes or repos that require it):

Help the user write an issue description (they write it, LLM reviews). If a template was found in step 6, the description must follow that template's structure.

Issue writing rules:

• Title: what's wrong, in under 10 words. Not "Issue with...". State the problem directly
• Body: the reproduction from step 6, expected vs actual behavior, that's it
• No filler, no "I believe", no "it seems like". State facts
• No AI jargon: "comprehensive", "robust", "fundamental". Cut all of it
• If you can't describe the issue in 5 lines, you don't understand it well enough yet

gh issue create -R {owner}/{repo} \
  --title "{descriptive title}" \
  --label "{label1}" --label "{label2}" \
  --body "$(cat <<'EOF'
{user's issue description. following template structure if one was found in step 6}
EOF
)"
# Omit --label flags entirely if no labels from template. Use one --label per label.

Then → oss-find-issue (claim the issue they just filed) → oss-contribute → oss-submit-pr

Option B: Fix directly (for small, obvious fixes in repos that accept unsolicited PRs):

→ oss-contribute directly. skip to the implementation phase

9. Track findings

Maintain a summary:

## Code Analysis: {repo}

| # | Finding | Category | Severity | User verdict | Action |
|---|---------|----------|----------|-------------|--------|
| 1 | Missing null check in auth | Error handling | High | Worth fixing | Filed #456 |
| 2 | Inconsistent date format | Inconsistency | Low | Not worth it | Skip |
| 3 | No test for edge case X | Test gap | Medium | Good find | Will fix with #456 |

Related Skills

• Next step (file issue): → oss-find-issue: to claim the issue you just filed
• Next step (direct fix): → oss-contribute: to implement the fix
• Preparation: ← oss-explore-repo: build broad understanding before looking for issues
• Previous step: ← oss-prep-to-contribute: should understand the codebase first
• Alternative to: ← oss-find-issue: when no existing issues match your skills, find your own

Common Rationalizations

Red Flags

• All findings are severity "low". You're finding cosmetic issues, not real problems
• Findings cluster in one file. you may be looking too narrowly; expand to other modules
• User agrees with every finding without pushback. they're not evaluating critically
• Repo's CONTRIBUTING.md says "file an issue before submitting PRs" but user wants to skip straight to fixing

Verification Checklist

• Repo accepts unsolicited contributions (verified)
• Each finding has a specific file:line reference
• Each finding has a clear impact statement (what could go wrong)
• User evaluated each finding and gave a reasoned verdict
• Every finding reproduced, not just read (step 6)
• Open and closed issues and PRs searched for prior art (step 6)
• Checked whether a test already asserts the behaviour (step 6)
• High-severity findings were filed as issues (if repo requires it)
• Issue descriptions follow repo template (if one exists)
• Findings summary table maintained with user verdicts and actions

Anti-patterns

• DO NOT file issues for style preferences. "I'd do it differently" is not an issue
• DO NOT file a finding that was never reproduced. reading the code is not evidence
• DO NOT search only open issues. the explanation is usually in a closed one
• DO NOT call behaviour a bug when a test asserts it. that is a disagreement with a decision, and it is argued differently
• DO NOT file issues without checking if the repo wants unsolicited contributions
• DO NOT present findings as definitive problems. always let the user evaluate and decide
• DO NOT submit fix PRs for issues you haven't filed first (unless the repo explicitly welcomes it)
• DO NOT run security scanners and dump the output. analyze, filter, and present only actionable findings
• DO NOT treat every finding as equally important. severity and maintainer-welcome-ness matter