OSS Contribution Research

Prepare one outside contribution to an open-source repo, gate by gate, and stop at a queue item a human approves. The agent running this skill never posts.

---

When to use

• Picking up an existing issue or confirmed bug in a repo the user does not maintain
• Checking whether a repo accepts AI-assisted pull requests before any work starts
• Asking a maintainer for a go-ahead before writing a patch (an intake comment)
• Turning a fix into a small, disclosed pull request draft that a human approves
• Following up on the user's own outside pull request: a review reply, the 14-day ping, or the 28-day close
• Running a contribution pipeline with an approval queue and a per-repo registry

When NOT to use

• Reviewing a pull request in a repo the user maintains (use code-review-web)
• Updating packages or lockfiles in the user's own project (use dependency-management)
• Writing a new feature spec for the user's own product (use pm-spec-writing)
• Writing a new skill for this catalog (use skill-creation-walkthrough)
• Unsolicited refactors, rewrites, or features in someone else's repo. This skill refuses them.

---

Required inputs

• Target. The repo (owner/repo) and one of: an existing issue or pull request URL, a bug the agent can reproduce, or a request to search the repo's open issues for a candidate.
• Queue snapshot. Each run starts on the user's normal login. It makes read-only (GET) calls to the user's private approval queue repo and exports a snapshot to a local file. The snapshot holds three things:
  • the registry (registry.yaml), with each repo's policy class, disclosure template per action type, review mode, cadence cap, cached last submission date and status;
  • the posted ledger: issues labeled status:posted, with the poster's posted markers;
  • the pause state: whether any open issue is labeled pipeline:paused.
• A read-only token. After the snapshot is written, the run switches to a read-only forge token for all outside research and patch work. It reads the queue only from the snapshot.
  • Filing. Filing the finished item into the queue is a separate, internal step on the user's normal login.
  • Posting. Posting to the outside repo happens only through the queue's poster, and only on approved items.
  • Freshness. The poster revalidates everything at post time, so the snapshot is never the last check.
• A local clone of the target repo on a branch the user's fork can push later.

If the snapshot is missing, stop and ask for it. Do not infer a policy, a disclosure template, or a submission history.

---

The framework: gates in order, stop at the first fail

Each gate either passes with evidence or stops the run with a reason. A stop is a valid result. Report it; do not route around it.

1. Pipeline gate. A pipeline:paused issue in the snapshot stops everything (kill switch).
2. Repo gate. Classify the repo's AI-PR policy as allows, silent, or bans, with the cited line (see references/policy-classification.md). Stop on bans, and stop when the registry status is not active. Stop in each of these cases too, with no exception for a fuller review flow: an excluded repo stays excluded.
   • The policy requires the human owner to attest to reviewing the complete change.
   • The repo accepts issues but not pull requests.
   • The repo accepts pull requests only from members.
3. Ownership gate. Before any throttle or duplicate check, classify the target as the user's own work or someone else's.
   • Own work. The user's own open pull request, or the user's own claim or intake comment on the issue. It routes to a follow-up item, not a block:
     • a review reply;
     • the 14-day ping (reply with purpose: ping);
     • the 28-day close (close);
     • after an approved intake, the pr item itself.
   • Competing work. Another person's PR, assignment, or claim. It goes to gate 5, which stops.
4. Throttle and cadence gate. This gate applies to new pull requests only, not to replies or closes on the user's own work.
   • Stop if the user already has a different open pull request on this repo.
   • Stop if the cadence cap says the next submission is not due. Take the last submission date from the snapshot's posted ledger. The registry's date is a cached hint only; when the two disagree, the ledger wins.
5. Duplicate and claim gate. Search open and closed pull requests and the issue thread. Stop on someone else's open pull request, assignment, or "working on this" comment.
6. Issue gate. Work only on an existing issue or a bug confirmed by reproduction. No unsolicited refactors or features.
   • Bug or small fix, from the body. Judge it from the issue body and thread. Labels are a hint only: a repo can have a bug label that none of its open bugs carry.
   • Still exists on the default branch. Check the current default branch, not only the issue's timeline. Search recent merged pull requests and commits that touch the relevant code, including ones that never link the issue. A -linked:pr filter misses them. Stop if the bug is already fixed; the issue is stale-open.
   • Claims are not facts. A bystander's "already resolved" or "can be closed" comment is a claim to verify against the code, not a result. It can cite the wrong commit and still reach the right conclusion, or the reverse.
7. Intake gate. Where the repo asks for maintainer assignment, an accepted label, or a go-ahead, and none exists yet, the output is an intake queue item (a short comment asking to take the issue). No patch is written until the go-ahead arrives.
8. Repro gate. A failing test or a documented reproduction exists before any fix.
9. Patch. The smallest single-purpose change that fixes the issue, in the repo's own style.
10. Checks gate. The repo's own test suite and linters pass locally, at the commit that will be submitted.
11. Size gate. The change is reviewable in under 5 minutes from a 3 to 5 sentence summary. If not, split it or drop it.
12. Critic gate. A separate agent reruns the reproduction and the test suite itself, at the exact head commit, on a different model family where one is available. Re-reading the diff does not count. A critic fail blocks the item.
13. Disclosure. Fill the item's structured Disclosure field from the registry template for this repo and this action type: pr_description, issue_comment, or review_reply (also used for a close).
    • none. The disclosure text is none.
    • unknown. Stop.
    • Template with slots. Fill every {slot} with what actually happened and put that exact line in the text to post (see references/pr-description-template.md).
    • No attribution. Where a repo forbids AI attribution, no tool name, trailer, or co-author line appears in the pull request body or in any commit.

Operating constraints that sit across every run:

• Kill switch. Any close of the user's pull request that cites AI or low-quality automated work pauses that repo and the pipeline.
• Stale rule. One polite ping at 14 days of maintainer silence, then a close at 28 days if still silent. Both are queue items the poster sends; neither is posted by hand.
• Actions. The poster sends exactly four actions: intake, pr, reply, and close. Nothing outbound happens outside them.

---

Workflow

1. Snapshot, then switch. On the user's normal login, export the queue snapshot (registry, posted ledger, pause state) with GET calls only. Then switch to the read-only token and confirm it is the one in use: gh api user names the expected account, and gh api rate_limit answers on that token.
   • Write-refusal probe: the user runs it, never the agent. Once per token, and again after any token renewal, the user runs a POST with no title to an issues endpoint on a repo of their own, for example gh api -X POST repos/<user>/<own-repo>/issues -f body=probe. A missing title means it cannot create a real issue. Expected: 403, so writes are refused. A 422 means the token can write; stop and replace it.
   • The agent does not run the probe, even if asked to retry it. If the user has not recorded a 403 for the current token, say so in the report and keep every call a GET.
   • Agent shells. Many agent shells start a fresh process per command, so a token set in one command is gone in the next. Start the agent from a terminal where the read-only token is already set.
2. Run gates 1 to 3 from the snapshot, the repo's guidance files, and the target thread. Record each result with a link. If gate 3 finds the user's own work, draft the follow-up item and skip to step 9.
3. Run gates 4 to 6 for new work. When the target is a candidate search, run them per candidate:
   • Listing. For a repo with a small open-issue count, list with the issues endpoint (GET /repos/{owner}/{repo}/issues?state=open, core quota) and skip pull requests in the result. The search API has a secondary rate limit that can trip after a handful of calls.
   • Order. Sort by recent update. Drop feature and docs proposals first, with a one-line reason each.
   • Result. The first candidate that passes every gate continues to step 4. If none passes, write the no-eligible-candidate report (see Output format) and stop.
4. Decide the action type. No go-ahead where one is required: draft an intake item and skip to step 9. Go-ahead in hand, or none required: continue.
5. Reproduce. Write the failing test or the reproduction steps. Run it and keep the output.
6. Patch and check. Make the smallest fix. Run the repo's tests and linters. Fix only what the change broke. Push the branch to the user's fork and record the full head SHA and the base SHA it was built on.
7. Size it. Write the 3 to 5 sentence summary first. If the summary cannot carry the change, split or drop.
8. Hand to the critic. Give the critic the repo, the branch, the head SHA, and the reproduction. It reruns both on its own and reports PASS or FAIL with output and the SHA it ran.
9. Draft the exact text. Pull request title and body, intake comment, reply, or closing comment, with the disclosure line from the registry template. See references/pr-description-template.md.
10. Build the queue item. Fill references/queue-item-template.md exactly:
    • a unique item_id;
    • for a pr, the head and base SHAs;
    • one structured result per gate;
    • the Disclosure field;
    • the full diff of base_sha...head_sha when the registry sets review_mode: full-diff;
    • the sha256 of the exact text block.
11. Stop. Return the queue item to the user. Filing it in the queue is a separate step on the user's normal login, not on the read-only token. Posting happens only through the queue's poster after the user approves.
    • File only a passing item. Filing happens only if a candidate passed every gate. A stop report or a no-eligible-candidate report is never filed as a queue item, whatever a run plan says.

---

Failure patterns

• Patch before intake. Writing code for an issue the maintainers have not opened to outside work. Their auto-close bots do not read the diff.
• Policy by vibe. Calling a repo allows because it has a friendly README. Cite the line or write "none found".
• One footer for every repo. Some repos forbid AI attribution in bodies and commits; others require a fixed disclosure line. The registry template decides, per action type.
• Blocking on your own work. Treating the user's own open pull request or claim as a duplicate. Gate 3 routes it to a reply, ping, or close.
• Summary that is a test log. "All 214 tests pass" is a gate result, not a summary. The summary says what changed and why, in words the user can repeat to a maintainer.
• Critic that re-reads. A second agent agreeing with the diff proves nothing. The critic reruns the reproduction and the suite at the head SHA.
• Moving the branch after approval. Any push after the item is filed changes the head SHA, and the poster refuses the item. File a new item instead.
• Volume. Several pull requests to one repo in a week reads as automation, whatever the quality. The cadence cap exists for this.
• Labels as the bug test. Filtering to the bug label and calling the pool empty. Read the bodies.
• Fixed but still open. Taking an open issue as proof the bug exists. A merged pull request that never linked the issue can already have fixed it. Check the default branch.
• Bystander verdicts. Closing out a candidate on a "can be closed" comment without checking the code it names.
• Search API for a small repo. Burning the search secondary rate limit on a repo with a few dozen open issues. List them on the core quota.
• Trusting a cached date. Reading the last submission from the registry when the posted ledger says otherwise. The ledger is the record; the registry date can lag.
• Silent scope creep. Fixing a neighboring bug or reformatting a file in the same diff. Split it or leave it.
• Posting from the research session. Any outbound write from this skill is a defect, including a "quick" comment asking to be assigned.

---

Output format

One queue item in markdown, ready to be filed as an issue in the user's approval queue. The structure, section headings, field names, and hash rule are fixed; see references/queue-item-template.md. A worked intake example is in references/example-intake-item.md.

When a gate stops the run, the output is a short stop report instead: the gate, the reason, the evidence link, and what would clear it.

When a candidate search finds no candidate that passes every gate, the output is a no-eligible-candidate report:

• the repo, the date, and how the pool was listed (endpoint, filters, count of open issues);
• every candidate checked, each with the gate it failed and the evidence: a link plus the line, comment, pull request, or commit that decided it;
• proposals dropped as out of scope (features, docs), one line each;
• what would change the result, such as new issues or a stated recheck date.

Neither report is a queue item, and neither is filed.

---

Reference files

• references/queue-item-template.md - The exact queue-item format, the structured gate and disclosure fields, and the hash rule. Read before step 10.
• references/policy-classification.md - Where to look for an AI-PR policy, how to classify it, how to cite it, and the eligibility stops. Read during gate 2.
• references/pr-description-template.md - Drafting the exact text per action type with per-repo disclosure. Read at step 9.
• references/example-intake-item.md - A filled intake queue item for a fictional repo.