When to Use
Before creating or suggesting a pull request to ANY repository. Acts as a quality filter to prevent wasting maintainer time and embarrassing the contributor.
Quick Reference
| Domain | File |
|---|---|
| Pre-submission checklist | checklist.md |
| Red flags to avoid | red-flags.md |
| Repository context gathering | repo-context.md |
| PR description templates | templates.md |
Critical Rules
- Read CONTRIBUTING.md first — Adapt to project's workflow, not a fixed pattern
- Issue policy depends on scope — Small fixes may PR directly; features need discussion first
- Disclose AI involvement — Mark AI-assisted PRs in title/description
- Run checks if possible — If you can't run tests, say so explicitly
- Match existing style — Check for
.editorconfig,prettier,eslintconfigs - Small and focused — One logical change per PR
- No secrets ever — Use
<PLACEHOLDER>syntax
Issue Policy (Contextual)
NOT all projects require issues first. Check CONTRIBUTING.md, then:
| Change Type | Default Action |
|---|---|
| Typo, small bug fix | PR directly (unless CONTRIBUTING.md says otherwise) |
| New feature | Open Discussion/Issue first, wait for approval |
| Architecture change | RFC or Discussion required |
| When in doubt | Ask in issue before coding |
AI-Assisted PRs
If this PR was created with AI assistance:
- Mark it — Add
[AI-assisted]to PR title or note in description - Testing level — State:
untested/lightly tested/fully tested - Include context — Prompts or session logs if available and helpful
- Confirm understanding — "I have reviewed this code and understand what it does"
- Human accountable — Link to the human directing the contribution
Rate Limiting (Avoid Spam)
- MAX 1 open PR per repo at a time
- Wait 24h between PRs to same repo
- If 2 PRs rejected consecutively → STOP and escalate to human
- Check repo's PR velocity first (don't flood low-activity projects)
Abandonment Prevention
- MUST respond to review feedback within 48h
- If unable to address feedback, close with: "I cannot continue; @human please take over or close"
- Never leave PRs to rot
Scope Boundaries — STOP and Discuss First If:
- Change touches >5 files OR >200 lines
- Change modifies public API
- Change involves security, auth, or crypto
- Change is in governance, licensing, or CoC
- Maintainer requested discussion in issue
- You're unsure if this aligns with project philosophy
Human Escalation Required
Escalate to human when:
- Reviewer asks clarifying questions about design intent
- CI fails in non-obvious way
- Any pushback beyond "fix this typo"
- Reviewer seems confused or frustrated
- You can't run the test suite locally