Skip to content

katopz/katgpt-rs / .agents/skills/pr

Universal Do/Don't doctrine for opening and maintaining upstream pull requests as an agent — the trust rules distilled from real campaign rounds (slop tells, review-comment handling, CI triage, reply voice, force-push hygiene, rate ceilings). Use when opening a PR to any external repository, responding to a maintainer review, deciding whether a change is PR-worthy, writing or rewriting a PR/comment body, or triaging red CI on our PR; also when asked "how do we PR into X". Complements the campaign-specific skills (riir-refine's outbound-pr = the gated healer campaign lane; this one is the repo-agnostic etiquette + failure taxonomy).

pr — upstream pull-request Do/Don't (agent doctrine)

Every rule below is something a real round paid for. Cite-the-round examples are from mozilla/sccache PR #2977 (the worked example, 6 rounds, 3 owner corrections, 2 CI breaks). When a campaign lane has its own skill (e.g. outbound-pr), that skill's gates stack ON TOP of these — these are the floor, not the ceiling.

The one principle

The PR is the fix + the verification story — nothing else. Every other rule is this principle applied to a surface: the diff, the body, the reply, the cadence.

DO

  • Do derive every factual claim from the primary source, in the same session. Tool lists, config defaults, spec quotes, "their CI runs X" — fetch/grep the primary source before the claim is written. (Failure: "rsync with an exclude plugin" — rsync has no CACHEDIR.TAG support; the spec's own page lists it under "not directly sensitive". Caught by an external verdict; would have been caught by one curl.)
  • Do make the body agree with the diff. After writing the body, re-read the diff and check every behavioral sentence against it. (Failure: body said "logs a warning", diff called error!.)
  • Do quote their exact numbers/defaults, not vibes. ("defaults to 10 GiB" not "can grow to tens of GB" — their config has the constant.)
  • Do verify at THEIR toolchain. rustup their MSRV (rust-version field > rust-toolchain.toml > clippy.toml > ABSENT ⇒ refuse, never guess); run their CI's exact clippy flags; their fmt. The local bar is not the bar.
  • Do bench-then-PR for any perf claim. Before/after at the target repo, pinned harness, box provenance (load/RAM/power beside every number). A number you have not measured does not ride.
  • Do answer reviews in short plain sentences. Name the commit sha. Use their vocabulary. One idea per line. Open with the substance (the catch, the mechanism), not a pleasance ("Thanks for the quick review! Fixed all four:" is a ledger, not a reply).
  • Do own misreads in one clause. "— sorry, I misread it as a main issue earlier" and move on. Over-apologizing reads worse.
  • Do patch existing comments (API PATCH) instead of posting duplicates.
  • Do reply to the reviewer's inline thread, not the main PR discussion. A review comment is a thread — reply with POST /repos/{repo}/pulls/{n}/ comments carrying in_reply_to: <their comment id>, so the answer lands under their line where they read it. A reply posted as an issue comment or a top-level review comment orphans the thread and reads wrong (measured: the #3025 maintainer round — our first replies went to the main discussion and the owner called it out; the fix round went in_reply_to and the threads read clean).
  • Do re-grep the touched FILE for the pattern a review comment flagged before pushing. A review comment is a CLASS signal, not a line signal. (Failure: maintainer flagged the hardcoded literal + manual read in the product; we fixed the flagged lines but 4 more literals + the same dance survived in the test 20 lines below — one more round.)
  • Do acknowledge an existing claimant before sending. Read the issue's comments for "I'd like to work on this" — a PR over an unacknowledged open claim reads as sniping. One plain sentence naming the earlier offer ("X offered to pick this up; if you've started, glad to fold this into yours"), or take the design-comment-first lane on contested issues: post the shape on the issue, open the PR after a reply. (Caught by the hard verdict on our second sccache PR — darshpatel1052 had claimed the work two days before; our body answered his design question but never acknowledged the claim.)
  • Do ship the docs row in the same PR. A new env knob, flag, or config surface gets its entry in THEIR docs file in the same change, in the file's own voice. The docs file is a reader of your surface — an undocumented knob is a near-certain review round (and the FC10 class: the sibling knobs were documented; ours weren't).
  • Do sweep the composite layers that route through your seam. Every wrapper/composite/dispatch that calls what you changed is a reader — a gate added at a storage seam skips the healthy local tier of a multilevel wrapper too (the M3 catch: MultiLevelStorage's read loop, three files from the diff, no tree-walk grep finds a call-graph edge). Grep for CALLERS of the modified functions, not just walkers of trees.
  • Do name the workload shape beside every number. "Sequential" vs the issue's parallel repro changes the result (in-flight probes multiply under -j); if the issue ships a repro script, run it before/after or state explicitly that its workload was not measured. A ratio that carries over only in one shape is scoped to that shape IN THE BODY.
  • Do answer every requirement the issue states. The issue's stated requirements are a checklist — each gets a body answer or an explicit "not addressed". (Miss: the issue said "avoid overreacting to transient slowness"; our body never said how correlated timeouts under parallelism don't trip the gate at once.)
  • Do run a stale-event audit on any state machine your diff adds. Every async completion path (a timeout, a cancel, a drop guard, a late response) that clears or resets shared gate/reservation state must carry the identity it belongs to — an admission id, a generation counter — so an OLDER read's completion cannot clear a NEWER reservation. Walk the overlap yourself before sending: cooldown shorter than the timeout, a read admitted pre-gate still pending, the reservation armed meanwhile — whose timeout lands next, and what does it clear? Ship the overlap regression in the same PR (measured: the #3025 maintainer round caught exactly this — our half-open recovery cleared the probe window on ANY timeout, so an older read's late timeout admitted a second probe while the first was pending; one generation counter + one identity-checked clear + one regression walking the maintainer's sequence closed it).
  • Do verify a zero before claiming it. A "clean / 0 findings" claim carries its completion marker — the tool's build-finished/success line, a non-empty capture, stderr collected (never /dev/null). A command that dies before compiling (wrong flag order: lint -A flags before --) produces an empty capture that reads as a green zero. The pre-existing baseline is adjudicated FIRST: same command on pristine main, failures named, then read your tree as a delta against it.
  • Do count the staleness. Before reusing any earlier pin, git rev-list --count <pin>..origin/main — never eyeball. The readiness verdict caught "two commits" that were 21, three of them bench-load-bearing. Re-run the gates whose inputs moved.
  • Do grep EVERY walk/scan of any tree your new file lands in. Adding a file to a repo means every recursive iteration over that tree now sees your file — find them all before pushing, not in someone's CI. (Failure: a CACHEDIR.TAG broke --debug-preprocessor-cache's third walk; two CI runs and a freebsd log line to find it.)
  • Do rebase onto current main before every push and re-check whether a maintainer fixed your issue upstream mid-review (the lockfile we shipped was superseded by the maintainer's own identical commit the same day).
  • Do force-push with the same branch name (refine/<topic>) during an open review round — it keeps the PR thread one diff. New commits only for separable concerns a maintainer might cherry-pick or drop independently.
  • Do keep fixes the maintainer can drop independently in separate commits (e.g. an incidental lockfile fix as its own deps: commit).
  • Do check repo house style for commit prefixes (deps:, fix:, whatever their history shows) and match it.
  • Do stop and report "nothing to send" as a PASS. A clean tree at their posture means the gate worked. A manufactured PR is the failure.
  • Do expect first-contribution CI to need a maintainer's "approve and run" (action_required state) — say so in the reply rather than re-pushing to trigger it. (Some repos auto-run on fork PRs — #3025's checks started within a minute.)
  • Do classify first responders by author_association, not by surface text. Bots (Codecov, clippy, merge automation) post the first comment on most PRs; a scary "patch coverage X%, N lines missing" report is TELEMETRY, not a maintainer review — author_association: NONE + a bot login means no reply, no reaction, no re-push. Record the bot in the per-repo CI surface map. (Worked example: Codecov opened #3025's thread minutes after the send; the alarming −6.77% project delta was its own "HEAD has 9 uploads less than BASE" artifact — a fork PR uploads coverage from fewer CI jobs than main, so the project delta always reads as a fake regression; the real signal is patch coverage on the added lines, and only a maintainer's question makes it actionable.)
  • Do silence the fork's own workflows at send time. Pushing a branch to the fork fires their push-event workflows IN THE FORK, where secret-dependent steps (Codecov token, deploy keys) fail loudly — and those runs NEVER appear on the PR's checks panel (which aggregates base-repo-context runs only), so the reds are invisible on the PR but read as "our fork CI is red" to any later agent. After the branch push: disable each fork workflow (gh api -X PUT repos/<org>/<repo>/actions/workflows/<name>/disable), cancel queued runs, note it in the send record. (#3025: integration-tests.yml failed at the Codecov upload — "Token required - not valid tokenless upload" — while the mozilla-side upload worked fine, proving coverage was measured where it matters.)

DON'T

  • Don't add attribution/disclosure/self-promo — no "Generated by X", no tool name, no site link, no logo, no repro-advertising, no aggregate stats. (Owner ban 2026-11-02: AI slop + shameless self-promo; public-goods posture keeps it out until the grant lands.) The proof is the fix + the verification story.
  • Don't send a PR whose purpose is "having sent a PR". If the scan says nothing, the round is a pass. A hand-authored non-evidence PR under a campaign banner is the Goodhart failure. (Failure: a convenience-feature PR sent as "evidence" — the owner's verdict: goodwill, outside the ledger, and it evidences nothing.)
  • Don't invent a new lane mid-round to justify a send. Campaign/marketing posture is the OWNER's call (what counts as evidence, what we send into). Surface the options and wait if the scan came back empty.
  • Don't fix only the flagged lines. (See the re-grep DO.)
  • Don't trust your first root-cause read of a CI failure. Reproduce locally, read the actual log lines (the failing stderr usually names the file — one freebsd log line contained the whole answer), and check whether the failure reproduces on a clean checkout of their main BEFORE writing "reproduces on main" in any reply. (Failure: we misattributed an entry format 53 failure to their preprocessor rework; it was our file; the reply had to own it a round later.)
  • Don't expect their CI to be green, or to run at all. First-contribution CI is maintainer-triggered (action_required) — zero runs for days is normal, and when runs appear, main's own pre-existing reds ride along (13 red jobs on our PR's first CI, all ONE upstream test broken by their own commit). Classify reds by grepping their logs for YOUR artifact names, never by job name; say so in the reply rather than re-pushing to trigger it.
  • Don't diagnose lockfile/dependency failures from the error text alone. --locked failures: read the manifests of the involved crates in the registry (pinned reqs vs resolved versions) and check whether MAIN's lock is the broken thing. (Failure: "unpinned dep" — both versions pinned = "0.12"; main's lock was hand-merged inconsistent.)
  • Don't downgrade/upgrade deps inside a feature PR. Minimal resolver delta, separate commit, or leave it to the maintainer.
  • Don't run repo-wide tools (fmt, tests, cargo commands) from the wrong working directory. A cargo fmt with the wrong cwd reformats someone else's worktree — 52 files of sibling WIP in one incident; recovery was mtime triage + targeted checkout. Check pwd against the manifest you mean. Never cargo fmt --all in a repo with intentional drift or siblings.
  • Don't pile a competing PR onto another contributor's open PR without an owner call, and don't argue in maintainer threads — rework or accept the close.
  • Don't exceed ≤3 PRs/day across the campaign, one PR per repo ever, never a re-PR after a close. A repo block = permanent blacklist. Never CLA/DCO auto-sign — skip those repos.
  • Don't file issues on external repos (the maintainer thread is the channel), don't auto-merge, don't ship dependency-bump PRs, don't send security findings as PRs (suggest-only, private disclosure path).
  • Don't keep persistent copies of their code. Clones are ephemeral (.raw/, removed at close-out); only derived data (rule ids, shape classes, outcomes) survives in anything that ships.
  • Don't let a per-file edit tool stitch long ledger/record lines. When updating round-based records, prefer appending whole rows or scripted replace with uniqueness asserts — three repair incidents in one record came from replace-instead-of-prepend edits.

The pre-push checklist (60 seconds, every push)

  1. pwd is the repo you intend; branch is yours; base is current main — and the staleness is COUNTED (git rev-list --count <base-pin>..origin/main), with the gates whose inputs moved re-run.
  2. Every factual claim in body/reply has a primary-source check this session.
  3. Body agrees with the diff; no attribution block; no unearned numbers; the workload shape is named beside every number; every requirement the issue states is answered or explicitly not addressed.
  4. Re-grep the touched files for the patterns already flagged in review; the composite layers routing through your changed seams are adjudicated; new env knobs have their docs rows; every async completion path that clears shared state in your diff carries the identity it belongs to (the stale-event walk: an older read's timeout/cancel must not clear a newer reservation), and the overlap has a regression.
  5. Their MSRV: tests green, their CI clippy flags clean, fmt clean — every zero carries its completion marker (build-finished/success + non-empty capture + stderr collected), and the pristine-main baseline was adjudicated first so reds read as a delta.
  6. The issue's comments checked for claimants; any claim acknowledged in the body.
  7. Diff contains only intended hunks (git diff read top to bottom).
  8. If perf claim: bench exists, box provenance recorded.
  9. If review response: every inline comment answered IN ITS OWN THREAD (in_reply_to, never the main discussion), reply is short/plain, commit shas in the reply match what you're pushing, and the delegated verdict ran BEFORE the fix and the reply (diagnosis + planned fix + reply drafts go to the verdict first; the implemented diff goes back for a second round before push).
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall