Add expected PR size bounty guidance [Bounty #383]

.github/pull_request_template.md

@@ -5,6 +5,10 @@
 ## Evidence
 
 - Confusion, missing step, stale example, or bug this addresses:
+- Bounty capacity and active attempts/open PRs checked:
+- Intended files or surfaces:
+- Expected PR size:
+- Out of scope:
 
 ## Test Evidence
 

docs/agent-guide.md

@@ -202,13 +202,15 @@ Use this checklist before opening a PR for `mrwk:bounty` issues:
 1. Confirm no active claim or duplicate PR already covers the same scope.
 2. When the bounty is active and has open award slots, register an advisory
    attempt with `/api/v1/bounties/{id}/attempts` before opening a PR.
-3. Keep changes small and directly tied to one bounty issue.
-4. Include `Bounty #<issue>` or `Refs #<issue>` in PR body.
-5. Explain the exact user or maintainer pain point you fixed.
-6. Include evidence: command output, screenshot, or clear reproduction steps.
-7. Run the required checks from the issue text (for docs work, run
+3. Write the claim-window scope before coding: exact bounty, intended files or
+   surfaces, expected PR size, test plan, and what is out of scope.
+4. Keep changes small and directly tied to one bounty issue.
+5. Include `Bounty #<issue>` or `Refs #<issue>` in PR body.
+6. Explain the exact user or maintainer pain point you fixed.
+7. Include evidence: command output, screenshot, or clear reproduction steps.
+8. Run the required checks from the issue text (for docs work, run
    `./.venv/bin/python scripts/docs_smoke.py`).
-8. Avoid private data, secret material, and speculative price claims.
+9. Avoid private data, secret material, and speculative price claims.
 
 Common rejection reasons: duplicate scope, style-only changes without user
 impact, missing evidence, or ignoring issue-specific acceptance criteria.

docs/bounty-rules.md

@@ -80,6 +80,11 @@ PR bounty submissions should link the bounty issue with `Bounty #<issue>` or
 `Refs #<issue>`. Use a closing reference only when the issue should close after
 that PR.
 
+For bounty PRs, include the claim-window packet in the PR body: exact bounty
+reference, intended files or surfaces, expected PR size, test plan, evidence,
+and out-of-scope notes. If the diff grows beyond the expected size, split it or
+explain why the larger review remains focused.
+
 Paid bounty links are tracked in
 [docs/paid-bounties.md](paid-bounties.md) and the public
 [GitHub discussion](https://github.com/ramimbo/mergework/discussions/16).

scripts/docs_smoke.py

@@ -24,6 +24,7 @@
 ]
 LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
 DOCS_ISSUE_TEMPLATE = ".github/ISSUE_TEMPLATE/docs.yml"
+PR_TEMPLATE = ".github/pull_request_template.md"
 
 
 def _local_target_exists(source: Path, target: str) -> bool:
@@ -63,6 +64,13 @@ def main() -> int:
         if "link the page, docs file, heading, command, or ui path" not in template:
             print("docs issue template location prompt must request actionable evidence")
             ok = False
+    pr_template = ROOT / PR_TEMPLATE
+    if not pr_template.exists():
+        print(f"missing pull request template: {PR_TEMPLATE}")
+        ok = False
+    elif "expected pr size:" not in pr_template.read_text(encoding="utf-8").lower():
+        print("pull request template must ask for expected PR size")
+        ok = False
     if ok:
         print("docs smoke ok")
         return 0