katopz/katgpt-rs / .agents/skills/pr
pr
VerifiedUniversal 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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.8 KB |
SKILL.md
View on GitHub---
name: pr
description: 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).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |