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

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

Author: batmn-dev

AGENTS.md

@@ -127,6 +127,10 @@ When the user asks to "create a prompt" (or similar), return the prompt directly
 Do not create a markdown file unless the user explicitly asks for a file.
 If ambiguous, prefer chat output.
 
+## No Timeline Estimates
+
+**Never include time estimates, durations, or effort assessments** in plans, summaries, or implementation outputs. This includes phrases like "~30 minutes", "2-3 hours", "Phase 1 (Day 1)", "Quick win", or any similar timeline/effort language. AI-generated timeline estimates are unreliable and misleading. Only include difficulty complexity risk estimates when appropiate.
+
 ## Critical Patterns
 
 ### Streaming Responses (MUST)
@@ -180,6 +184,7 @@ catch { if (previous) setState(previous) }
 
 ### 🚫 Forbidden
 
+- **Creating git branches** — NEVER create new branches unless the user explicitly asks for a branch to be created. Implementation plans, feature work, and all other tasks must be done on the current branch. Branch creation requires explicit user instruction.
 - Read/write `.env*` files
 - Force push or commit secrets
 - `// @ts-ignore` (never acceptable)
@@ -232,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

@@ -14,7 +14,7 @@ This file contains Claude-specific behaviors, preferences, and context for the N
 ### Response Style
 - Be concise; avoid over-explaining obvious code
 - Use code references (`startLine:endLine:filepath`) when discussing existing code
-- Prefer showing small, focused diffs over full file rewrites
+- **Never include timeline or effort estimates** (e.g., "~30 min", "2 hours", "Day 1") unless the user explicitly asks for them — AI time estimates are unreliable
 
 ### Tool Usage
 - **Maximize parallel tool calls** when operations are independent
@@ -184,6 +184,7 @@ Before writing code, follow this sequence:
 
 ### Forbidden Actions
 
+- **Creating git branches** — NEVER create new branches unless the user explicitly asks for a branch to be created. Implementation plans, feature work, and all other tasks must be done on the current branch. Branch creation requires explicit user instruction.
 - Setting ESLint rules to `"off"` or `"warn"` to bypass errors
 - Adding `// @ts-ignore` (never acceptable)
 - Adding `eslint-disable` comments without documented reason
@@ -217,6 +218,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.
 
 ---