| name | pull-request |
| description | Open a high-quality pull request for the post-for-me monorepo and wire it to its Linear issue. Use this skill whenever the user wants to open/create/raise a PR, "put this up for review", push a branch for review, or finalize a change for merge — even if they don't say the words "pull request". It covers branch naming (feat/fix/chore), the PR body template, tagging the Linear issue in the body so it auto-closes on merge, and auto-attaching the PR link to the Linear issue via the Linear MCP. Reach for it any time work is ready to become a PR. |
Opening a pull request
This repo is a dumb monorepo of independent siblings (api/, trigger/, dashboard/, marketing/). A PR almost always touches one sibling — keep it scoped, and run that sibling's checks before opening.
Work through these steps in order. The goal is a PR a reviewer can understand without opening the diff, linked to its Linear issue so status stays in sync automatically.
1. Branch
Branches are prefixed by change type. Only three prefixes — keep it simple:
feat/ — new functionality or user-facing capabilityfix/ — bug fix or correcting broken behaviorchore/ — everything else: deps, config, tooling, docs, refactors, test-only changes
Use a short kebab-case description: feat/posthog-conversion-tracking, fix/webhook-signature-check, chore/bump-react-router.
If the current branch is main or doesn't carry one of these prefixes, create a correctly-prefixed branch off main before committing — never open a PR from main. (The Linear-generated caleb/pfm-123-... branch names are fine too if one already exists; the prefix rule is for branches we create.)
2. Commit
Follow the repo's commit conventions (conventional-commit style, type(scope): summary, and the Co-Authored-By footer the harness requires). Commit and push only when the user has asked you to.
3. Identify the Linear issue
Find the issue this PR resolves. Look, in order:
- The branch name (
caleb/pfm-576-... → PFM-576).
- What the user told you in conversation.
- If neither, ask the user for the issue ID before opening the PR — the link/tag steps depend on it.
4. Write the PR body
The title should read like a conventional commit: type(scope): concise summary (e.g. feat(dashboard): track conversion events in PostHog).
Use this body template. Every section earns its place — a reviewer should grasp what changed and why without reading the diff, and know how you verified it.
## Summary
1–3 sentences: what this PR does and why it's needed. Lead with the user/business
reason, not the implementation.
## Changes
- The notable changes, as bullets. Group by area if the PR is large.
- Call out anything a reviewer should pay special attention to.
- Note new dependencies, env vars, or migrations explicitly.
## Testing
How you verified this works — commands run, manual steps, what you observed.
If something is untested or deferred, say so plainly.
## Notes
(Optional) Known limitations, follow-ups, or decisions worth flagging.
Screenshots/recordings go here for any UI change.
Closes PFM-XXX
🤖 Generated with AI
Guidance on the sections:
- Summary — the "why" matters more than the "what". A reviewer skims this first.
- Changes — bullets, not prose. Surface migrations / new env vars / new deps because they have deploy implications and are easy to miss in a diff.
- Testing — be honest. "Typecheck + lint pass; drove the real Stripe checkout flow against a local team and confirmed
customer_converted in PostHog" is far more useful than "tested locally". If tests failed or a step was skipped, report it.
Closes PFM-XXX — this magic word is required. On merge it auto-moves the Linear issue to Done. Use Closes (or Fixes) for the issue the PR resolves; for issues it only relates to, write Part of PFM-YYY so they aren't auto-closed.
5. Open the PR
Use the gh CLI:
gh pr create --title "type(scope): summary" --body "$(cat <<'EOF'
...body from the template...
EOF
)"
Capture the returned PR URL — you need it for the next step.
6. Link the PR and move the issue — via the Linear MCP
We have the Linear MCP, so do both of these directly rather than depending on Linear's GitHub automation:
-
Attach the PR as an explicit link on the issue (the manual "Add link / Ctrl+L" step), via the save_issue tool's links param:
id: the issue identifier (e.g. PFM-576)links: [{ "url": "<PR URL>", "title": "<PR title or 'GitHub PR #NN'>" }]links is append-only, so this won't disturb existing attachments.
-
Move the issue to In Review in the same save_issue call (state: "In Review"), so status reflects reality without relying on the GitHub integration being configured. (Merging still auto-closes it to Done via the Closes tag.)
After this, confirm to the user with the PR URL and the issue you linked + moved.
Quick checklist
