docs(contributing): search-first, linked issue, gates + Greptile bar (#7522)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - CONTRIBUTING.md and the PR template are the entry point for new
contributors and set quality expectations for every PR
> - Today they don't tell contributors to search for duplicate/related
work first, don't require a linked GitHub issue, and don't spell out the
merge bar (gates green + Greptile 5/5)
> - Letting duplicate or under-reviewed PRs land creates extra work for
reviewers and erodes quality
> - This PR updates CONTRIBUTING.md and the PR template to require a
search-first workflow, a linked issue, a clear merge bar, and explicit
encouragement to help other contributors land their PRs
> - The benefit is fewer duplicate PRs, easier triage, higher-quality
merges, and a kinder collaboration culture

## What Changed

- `CONTRIBUTING.md`: added a "Before You Start: Search First" section
directing contributors to search GitHub for duplicate PRs and related
issues, with a note that a fresh PR is okay if an old one is dead and
would be painful to merge.
- `CONTRIBUTING.md`: require every PR to link a GitHub issue in the
body, plus references to related/duplicate PRs and issues.
- `CONTRIBUTING.md`: added a section encouraging contributors to help
finish other people's PRs, thank collaborators, and be kind.
- `CONTRIBUTING.md`: tightened the merge bar — all Paperclip CI gates
must be green and Greptile must be 5/5 with no open P2s,
recommendations, or follow-ups.
- `CONTRIBUTING.md` + `.github/PULL_REQUEST_TEMPLATE.md`: updated the
thinking-path opener to "Paperclip is the open source app people use to
manage AI agents for work" (consistent across examples and template).
- `.github/PULL_REQUEST_TEMPLATE.md`: checklist gains items for
duplicate/related search, linked issue, gates green, and the Greptile
5/5 bar.

## Verification

- Docs-only change. Reviewed both files render correctly on GitHub.
- No code or tests affected; no CI behavior change beyond the new
checklist items contributors are asked to tick.

## Risks

- Low risk. Documentation and template only — no runtime impact.
Stricter contributor expectations may slow some PRs in the short term.

## Model Used

- Claude, `claude-opus-4-7` (extended thinking, tool use).

## Related

- Issue: #4188 — "Add issue templates and enforce issue-link check on
PRs" (the linked-issue requirement here is a step toward what #4188 asks
for, done in CONTRIBUTING/template rather than CI).
- Prior PR: #4260 — "docs: expand CONTRIBUTING.md and add issue
templates" (open; different scope — issue templates + broader expansion.
This PR is narrower and focused on the search-first + merge-bar
updates.)

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have linked the GitHub issue this PR addresses (and any
related/duplicate issues)
- [x] I have run tests locally and they pass (docs-only change; no tests
to run)
- [x] I have added or updated tests where applicable (N/A — docs)
- [x] If this change affects the UI, I have included before/after
screenshots (N/A — docs)
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green (will verify after push)
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
(pending review)
- [x] I will address all Greptile and reviewer comments before
requesting merge

CONTRIBUTING.md

@@ -4,6 +4,16 @@ Thanks for wanting to contribute!
 
 We really appreciate both small fixes and thoughtful larger changes.
 
+## Before You Start: Search First
+
+Before you start work, **search GitHub** for existing PRs and issues that touch the same area:
+
+- Look for **duplicate or in-flight PRs**. If something close already exists, prefer helping that PR over the line (see [Helping Other Contributors](#helping-other-contributors)) instead of opening a parallel one.
+- Look for **related open issues**. Link them in your PR body.
+- If an older PR is effectively dead (stale, unmaintained, would be painful to rebase/merge), a fresh PR is fine — just call out the prior PR in your description so the reviewer has context.
+
+Duplicate PRs create extra work for reviewers and make merging harder. A 60-second search saves hours later.
+
 ## Two Paths to Get Your Pull Request Accepted
 
 ### Path 1: Small, Focused Changes (Fastest way to get merged)
@@ -39,6 +49,18 @@ PRs that follow this path are **much** more likely to be accepted, even when the
 
 Every pull request **must** follow the PR template at [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). If you create a PR via the GitHub API or other tooling that bypasses the template, copy its contents into your PR description manually. The template includes required sections: Thinking Path, What Changed, Verification, Risks, Model Used, and a Checklist.
 
+### Link Issues or Describe Them In-PR
+
+We do not gate PRs on a pre-existing issue. Two acceptable paths:
+
+1. **Issue exists** — search the [Issues database](https://github.com/paperclipai/paperclip/issues) for anything this PR addresses and tag each one with `Fixes: #123` / `Closes #123` / `Refs #123` so GitHub auto-links them. If there are **duplicate or closely related issues**, link all of them, not just the one you picked. If there are **related PRs** (prior attempts, dependent work, follow-ups, abandoned predecessors), link those too.
+2. **No issue exists** — describe the problem directly in your PR body, following one of our [issue templates](.github/ISSUE_TEMPLATE/) so a reviewer has the same fields they'd get from a filed issue:
+   - **Bug fix:** what happened, expected behavior, steps to reproduce, Paperclip version/commit, deployment mode. See [`bug_report.yml`](.github/ISSUE_TEMPLATE/bug_report.yml).
+   - **Feature:** problem/motivation, proposed solution, alternatives considered, roadmap alignment. See [`feature_request.yml`](.github/ISSUE_TEMPLATE/feature_request.yml).
+   - **New adapter:** agent or provider, why it's useful, how it's invoked. See [`adapter_request.yml`](.github/ISSUE_TEMPLATE/adapter_request.yml).
+
+Either way, a reviewer should be able to understand the underlying issue without leaving the PR. Commitperclip may check that one of these two paths is satisfied.
+
 ### Model Used (Required)
 
 Every PR must include a **Model Used** section specifying which AI model produced or assisted with the change. Include the provider, exact model ID/version, context window size, and any relevant capability details (e.g., reasoning mode, tool use). If no AI was used, write "None — human-authored". This applies to all contributors — human and AI alike.
@@ -47,9 +69,31 @@ Every PR must include a **Model Used** section specifying which AI model produce
 
 All tests must pass before a PR can be merged. Run them locally first and verify CI is green after pushing.
 
+### Paperclip Gates Must Pass
+
+All Paperclip CI gates (lint, typecheck, tests, build, and any other required checks) must be satisfied before a PR can be merged. Don't ask for a merge while gates are red — fix them first.
+
 ### Greptile Review
 
-We use [Greptile](https://greptile.com) for automated code review. Your PR must achieve a **5/5 Greptile score** with **all Greptile comments addressed** before it can be merged. If Greptile leaves comments, fix or respond to each one and request a re-review.
+We use [Greptile](https://greptile.com) for automated code review. Your PR must achieve a **5/5 Greptile score** before it can be merged, with:
+
+- **No open P2 (or higher) comments**
+- **No open recommendations**
+- **No open follow-ups**
+
+We hold the bar high here on purpose — we want code quality to be as high as possible. If Greptile leaves comments, fix them (or, if a comment is wrong, reply explaining why) and request a re-review.
+
+## Helping Other Contributors
+
+Fixing up someone else's stalled or almost-there PR is **strongly encouraged**. If a contributor has done most of the work but ran out of time or got stuck, picking up their branch, polishing it, and getting it over the line is one of the most valuable things you can do here.
+
+When you do:
+
+- Give credit. Mention the original author in the PR description and thank them.
+- Preserve their commits where reasonable — don't squash them out of existence.
+- Be kind in comments and reviews. People put real effort into their PRs, even the ones that didn't quite land.
+
+A culture where contributors help each other ship is worth more than any single PR. Be generous with thanks.
 
 ## Feature Contributions
 
@@ -80,7 +124,7 @@ Your PR description must follow the [PR template](.github/PULL_REQUEST_TEMPLATE.
 
 ### Thinking Path Example 1:
 
-> - Paperclip orchestrates ai-agents for zero-human companies
+> - Paperclip is the open source app people use to manage AI agents for work
 > - There are many types of adapters for each LLM model provider
 > - But LLM's have a context limit and not all agents can automatically compact their context
 > - So we need to have an adapter-specific configuration for which adapters can and cannot automatically compact their context
@@ -89,7 +133,7 @@ Your PR description must follow the [PR template](.github/PULL_REQUEST_TEMPLATE.
 
 ### Thinking Path Example 2:
 
-> - Paperclip orchestrates ai-agents for zero-human companies
+> - Paperclip is the open source app people use to manage AI agents for work
 > - But humans want to watch the agents and oversee their work
 > - Human users also operate in teams and so they need their own logins, profiles, views etc.
 > - So we have a multi-user system for humans