docs: add PR creation guidelines to prevent stale local ref comparisons

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: batmn-dev

AGENTS.md

@@ -237,6 +237,15 @@ Use `ultrathink` for complex architectural decisions.
 
 See `.agents/workflows/development-cycle.md` for details.
 
+## Pull Requests
+
+When creating a pull request:
+
+1. **Always fetch first** — Run `git fetch origin` before comparing branches
+2. **Compare against remote** — Use `origin/main` (not local `main`) for diffs and commit logs. Local `main` may be stale.
+3. **Verify commit count** — Run `git log origin/main..HEAD --oneline` and confirm the number matches what GitHub will show
+4. **Scope the description** — The PR body must reflect only the commits unique to the branch, not the full history since an outdated local ref
+
 ---
 
 *~200 lines. For detailed patterns, see `.cursor/rules/` and `.agents/skills/`.*

CLAUDE.md

@@ -219,6 +219,7 @@ When debugging issues:
 - **Auth**: Uses Clerk for authentication; avoid touching `middleware.ts` without review
 - **File Storage**: Uses Convex storage for file uploads
 - **Model terminology**: See `.agents/context/glossary.md` for precise definitions
+- **Pull requests**: Always `git fetch origin` first and compare against `origin/main`, never local `main`. Local main can be arbitrarily stale, causing commit/diff inflation in PR descriptions.
 
 ---