Upstream Recon
Verified@SeMmyT
npx machina-cli add skill @SeMmyT/upstream-recon --openclawUpstream Recon
Investigate a repo's culture and existing threads before interacting. Prevents duplicate issues, wasted PR effort, and uninformed comments.
Arguments: <owner/repo> [topic-keyword]
Procedure
Use gh CLI throughout. Run independent queries in parallel.
- Repo metadata — stars, forks, license, last push date, archived status
- Top 10 contributors — commit counts. Is it one person with 90%+ commits?
- Existing issues search — search open AND closed issues for the topic keyword. Check for duplicates, prior art, and maintainer responses. Report what was found.
- Recent 30 PRs (all states) — get the lay of the land
- Merged PRs (last 20) — who merges them? How fast? What types get accepted?
- Closed-without-merge PRs (last 50, filter
mergedAt == null) — deep-dive 2-3 notable rejections: read comments for maintainer reasoning - Open PRs — how many sit with 0 reviews? For how long?
- Topic deep-dive (if keyword given) — read comments on 2-3 most relevant existing issues/PRs to understand maintainer sentiment and community workarounds
Analysis Dimensions
- Governance: Solo maintainer / small team / community-driven
- External PR reception: Welcoming / selective (bugs yes, features no) / closed shop
- Issue responsiveness: How fast do maintainers respond to issues? Do they engage or auto-close?
- Merge velocity: Days from open to merge for external contributors
- Rejection patterns: Ghosted? "Building it myself"? "File issue first"? Bot auto-closed?
- Topic overlap: Has this been attempted or discussed before? Active workarounds?
Recommendation
End the report with one of:
- MERGE-LIKELY — project merges external feature PRs, no competing work, maintainer receptive
- MERGE-UNLIKELY — maintainer builds features themselves, similar PRs closed/ignored, feature contradicts direction
- FILE-ISSUE-FIRST — feature not yet discussed, maintainer is selective but responsive to issues, gauge interest before coding
- COMMENT-ON-EXISTING — existing issue/PR already covers this, add your workaround or +1 there instead
- DUPLICATE-EXISTS — exact issue already filed, do not create another
Include concrete next steps (e.g., "comment on #13738 with your workaround", "start with a bug fix PR to build credibility", "file an issue referencing #189", "fork and maintain independently").
Overview
Upstream Recon investigates a repository's culture, issues, and PR history before you interact. It helps prevent duplicate reports, wasted PR work, and misinformed comments by surfacing governance patterns and maintainer sentiment.
How This Skill Works
Using the gh CLI, run parallel queries to collect repo metadata, top contributors, and activity across issues and PRs. Analyze governance, issue responsiveness, merge velocity, and rejection patterns, then derive a recommended action from MERGE-LIKELY, MERGE-UNLIKELY, FILE-ISSUE-FIRST, COMMENT-ON-EXISTING, or DUPLICATE-EXISTS.
When to Use It
- Before filing an issue
- Before submitting a PR
- Before commenting on an existing thread
- When you are interacting with a repo you don't maintain
- To check for duplicates and surface prior art before coding
Quick Start
- Step 1: gh repo view <owner/repo> --json stars,forks,license,pushedAt,archived
- Step 2: gh issue list --state all --search '<topic>'
- Step 3: gh pr list --state all; gh pr list --state merged --limit 20; gh pr list --state closed --limit 50
Best Practices
- Fetch repo metadata (stars, forks, license, last push, archived status)
- Inspect top 10 contributors and their activity
- Search open and closed issues for your topic keyword to detect duplicates and prior art
- Review recent and merged PRs to understand acceptance criteria and speed
- Read 2-3 relevant issues/PRs to gauge maintainer sentiment
Example Use Cases
- Trying to file a bug fix in a small library; check related issues and PRs first
- Planning a feature in a widely used tool; verify maintainer stance before drafting a PR
- Commenting on an issue; ensure your workaround isn't already discussed
- Assessing a repo with rapid PR turnover to tailor your contribution approach
- Forking and proposing changes only after confirming governance and velocity
