From 0ca1bd45bfc81104a40e01d922d11fa5e99827fa Mon Sep 17 00:00:00 2001 From: prettyboyvic <39074015+prettyboyvic@users.noreply.github.com> Date: Tue, 26 May 2026 15:46:22 +0700 Subject: [PATCH 1/2] Add expected PR size bounty guidance --- .github/pull_request_template.md | 4 ++++ docs/agent-guide.md | 14 ++++++++------ docs/bounty-rules.md | 5 +++++ scripts/docs_smoke.py | 9 +++++++++ 4 files changed, 26 insertions(+), 6 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1511edaa..ab486ca5 100644 --- a/.github/pull_request_template.md +++ b/.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 diff --git a/docs/agent-guide.md b/docs/agent-guide.md index 00e7b42e..baea8cf8 100644 --- a/docs/agent-guide.md +++ b/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 #` or `Refs #` 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 #` or `Refs #` 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. diff --git a/docs/bounty-rules.md b/docs/bounty-rules.md index c1b4028a..4f38f5da 100644 --- a/docs/bounty-rules.md +++ b/docs/bounty-rules.md @@ -80,6 +80,11 @@ PR bounty submissions should link the bounty issue with `Bounty #` or `Refs #`. 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). diff --git a/scripts/docs_smoke.py b/scripts/docs_smoke.py index f8fe1729..057024bb 100644 --- a/scripts/docs_smoke.py +++ b/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,14 @@ 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 + if ok: + 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 From 910f01b75e5fdc90f5b82567de4f8b03315d0ce1 Mon Sep 17 00:00:00 2001 From: prettyboyvic <39074015+prettyboyvic@users.noreply.github.com> Date: Tue, 26 May 2026 15:53:40 +0700 Subject: [PATCH 2/2] Address docs smoke review nit --- scripts/docs_smoke.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/scripts/docs_smoke.py b/scripts/docs_smoke.py index 057024bb..0b2de8c5 100644 --- a/scripts/docs_smoke.py +++ b/scripts/docs_smoke.py @@ -64,14 +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 - if ok: - 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 + 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