wakqasahmed External PR Style
Use this whenever opening a PR against a repository we don't own or control: any upstream, third-party, open-source contribution.
The problem
Some maintainers reject otherwise-correct, well-tested PRs purely because the description reads as AI-generated: generic section headers ("Root Cause:", "Why This Fix Works:", "Alternatives Considered:"), templated phrasing, over-explained one-line fixes. This is usually not an automated detector. It's a human maintainer pattern-matching by eye and closing with a canned rejection reply, sometimes on a diff that is otherwise correct and tested.
Maintainers in high-volume open-source repositories frequently pattern-match against common LLM artifacts: formulaic section headers, verbose explanations of trivial diffs, polite boilerplate, and hedging. Diffs that are completely correct and well-tested can be summarily closed if the PR text reads like an automated submission rather than a focused human contribution. Always inspect a target repository's recent merged and closed PR discussions to calibrate style before opening a PR.
Rules
- Write the PR body as first-person prose describing the bug and the fix, the way you'd explain it to a coworker over chat, not as a templated report.
- No invented section headers unless the target repo's own template requires them (see exception below). Skip "Root Cause:", "Why This Works:", "Alternatives Considered:", "Summary:" unless the repo asks for exactly that.
- State what you verified (tests run, red→green proof, residual risk on security-sensitive changes) as plain sentences woven into the explanation, not as a labeled checklist.
- Don't over-explain a small fix. Match the length of the description to the size of the change: for small fixes (1-20 lines), write 1-2 concise sentences describing the symptom and fix; for medium changes (20-100 lines), write one compact paragraph (3-5 sentences); for large changes (100+ lines), write two focused paragraphs detailing what changed, why, and what was verified.
- Don't hedge excessively or enumerate edge cases nobody asked about.
Em dashes are a tell
In our own PR litespeedtech/openlitespeed#509, the body and one follow-up comment used 5 em dashes across 661 words of prose combined, about 1 per 130 words. This is a concrete measured example, not a universal statistic; most engineers write many PRs without using one at all.
- Don't default to em dashes. Rewrite with a period, comma, colon, or parentheses according to the sentence's purpose.
- For two independent clauses, split them into two sentences or use "because", "so", or "and" when the relationship is genuinely causal. For an aside or clarification, use parentheses or a comma.
- If an em dash remains genuinely clearer after rewriting, use at most one in any PR body or individual comment. Apply the same ceiling to each commit message and review comment. More than that reads as templated.
- Apply this rule to every PR body, PR comment, commit message, and review comment governed by this skill, not only the initial PR description.
Compression pass (do this last, before posting)
Technique adapted from mattpocock/skills — caveman (filler/hedge/pleasantry stripping), applied to natural prose rather than caveman's fragment style to ensure PR descriptions read as clear, authentic engineer-to-engineer communication.
Long, padded explanations are themselves an AI-tell, independent of headers. Reread the drafted body and strip (see canonical prose compression word list):
- Pleasantries/hedging: "I'd be happy to", "please note that", "it's worth mentioning", "certainly", "of course", "I believe".
- Filler intensifiers: "just", "really", "basically", "actually", "simply", "essentially".
- Restated context the maintainer already has (the issue title, the file name, "as described in the issue").
- Any sentence that explains something the diff already makes obvious.
This is a compression pass on your own draft, not a caveman-style rewrite. Keep full sentences, articles, and natural grammar. The goal is a shorter draft that reads like a person who typed fast, not a person who dropped words to save tokens. If a sentence survives after removing every filler word from it, it earns its place; if it doesn't survive, it wasn't saying anything.
Exception: repos with a bot-enforced template
Some repos mechanically require specific sections (a PR-checks bot that blocks merge until a template is filled in, e.g. a required Summary/Why/How/Testing/Examples/Checklist structure, or a PR-title-lint bot with a fixed scope list). There, fill in exactly what's required. That's a hard requirement, not the AI-tell pattern: skipping it isn't concision, it's an incomplete submission that gets mechanically blocked before a human ever reads it.
Check for this before writing the PR body: look for .github/pull_request_template.md, a PR-checks workflow that validates title/body format, or CONTRIBUTING.md language describing a required structure. If one exists, follow it precisely. If none exists, default to natural prose.
Distinct from an explicit no-AI-contributions policy
Some repos state an outright policy against AI-assisted contributions (e.g. a maintainer-applied "rejected AI" label, or CONTRIBUTING.md language explicitly declining AI-generated PRs). That is a different, harder line than a style preference. Don't try to write around an explicit policy like that. Skip the repo entirely. This skill is about writing genuinely well for repos that judge quality and effort, not about disguising AI involvement where a maintainer has drawn an explicit line against it.
Commit messages
This governs PR descriptions only. Commit message attribution rules (no AI co-author lines, ever) are unaffected and covered separately in system-level/core.md: they apply regardless of which repo you're contributing to.