| name | pull-requests |
| description | Use when the user asks to open a PR or MR, draft a PR description, fill the PR template, request reviewers, or merge a PR in a Serokell repo. Triggers on phrases like "open a PR", "create a pull request", "make an MR", "write PR description", "fill the PR template", "request review", "merge this PR", "tick the checkboxes". |
Pull requests and merge requests
Use this skill when opening, updating, or reviewing a PR (GitHub) or MR
(GitLab).
Title
Scheme: [ISSUE-ID] Brief description.
- Omit
[ISSUE-ID] if the repository is public and the issue is in a
private tracker (e.g. YouTrack).
- Brief description: short but understandable on its own.
Description
Must not be empty.
- This repo provides templates at
.github/pull_request_template.md
(GitHub) or .gitlab/merge_request_templates/default.md (GitLab).
Use whichever applies to the host.
- Fill every section of the template (
Description, Related issue(s),
the various Checklist subsections, and Release Checklist where
applicable).
- Describe what changed AND why.
- Link related issues. For GitHub / GitLab public issues, use
Fixed #N / Resolves #N to auto-close them on merge. For YouTrack
issues, paste the full URL
(https://issues.serokell.io/issue/<PROJECT>-<N>) prefixed with
Resolves.
Checkboxes
This is the rule that catches people out:
- Tick every checkbox you can substantiate.
- If a checkbox is irrelevant to this PR, still tick it. That
signals you considered the item and judged it irrelevant. Do not
silently leave irrelevant items unticked.
- The only acceptable unticked checkbox is one you can justify (e.g.
in a PR comment).
The PR template itself states this explicitly in its meta-comments;
follow that instruction.
What each checkbox actually means
The PR template groups checkboxes into conditional sections. For each
one, know what triggers it and what evidence backs ticking it:
- Tests — fires when the PR adds functionality or fixes a bug. For
new functionality: add tests covering it. For a bugfix: add a
regression test that would have caught the bug.
- Documentation — fires when the PR changes behaviour visible to
users or to other code. Update the
README and in-code API
documentation as needed.
- Public contracts — fires when the PR changes public API or
protocol. Comply with the project's public-contracts policy
(semver, deprecation cycles, etc.), add a
CHANGES.md entry, and
provide a migration note for breaking changes.
- Release Checklist — fires on release PRs only. Bump the version
in the project's package manifest; add
@since-style annotations to
new public API where the language supports them; create the GitHub
releases entry after merge with the vX.Y.Z tag; publish to the
relevant package registry for public libraries (e.g. Hackage for
Haskell).
- Stylistic guide (mandatory) — never irrelevant. Confirm commit
policy compliance, plus code style compliance if the repo has a
style guide.
- Agent instructions (conditional) — fires when the PR touches
.claude/skills/ or .github/copilot-instructions.md. Keep the two
in sync: when one changes, verify the other still reflects the
changed content.
Scope
- One PR per issue (1:1 mapping). Don't bundle unrelated work.
- An exception: trivial in-place fixes (a typo, wrong formatting) in a
file you're already editing are fine.
- Size guideline: aim for ≤500 additions+deletions. If your PR is
larger, think first whether the issue can be split.
Reviewers
- Request review from the project's expected number of reviewers
(project-dependent, often 2). If unsure, check
CODEOWNERS and
recent merged PRs, or ask the user. Look for people who touched this
code before or are likely interested.
- Codeowners may be auto-requested; check the final reviewer list after
opening the PR.
During review
- Make requested changes in separate commits — do NOT amend earlier
commits during review. Use
git commit --fixup=<sha> (see the
committing-work skill).
- Do NOT force-push during review, except to rebase on a newer target
branch (and use
--force-with-lease, never -f).
- Sync with the target branch periodically by rebasing onto it, not by
merging it in.
- Do not mark a reviewer's comment as resolved. That is the
reviewer's call — they decide whether their concern was addressed.
- If reviewers don't respond within ~3 working days, ping them
explicitly. If still silent, ping the team lead too — tag their
username (from
PROJECT.md) in a comment.
Merging
- Use a merge commit (GitHub's "Create a merge commit" option).
- Do NOT use "Squash and merge" unless the PR has exactly one commit.
- Do NOT use "Rebase and merge" by default. (Exception: fast-forwarding
a release branch from
master.)
- Before merging, ensure the commit history satisfies the project's
commit policy (see the
committing-work skill). PR author usually
cleans history before merge.
- When merging someone else's PR: confirm the author is fine with
merging and doesn't want to touch the commit history first. If the
PR is trivial (e.g. a one-line fix) you can merge without asking;
otherwise ping the author. On GitLab, the author's self-approval
counts as agreement to merge.
