docs: add pre-bounty preflight checks and rejection recovery guide [Bounty #383]

[Karry2019web]

Summary

Add pre-bounty preflight checks and rejection recovery guidance to the docs.

Changes

docs/api-examples.md (+80 lines)

New Pre-Bounty Preflight Checks section with live API examples:

• Check bounty award capacity (/api/v1/bounties, /api/v1/bounties/summary)
• Inspect active attempts before registering your own
• Cross-reference open PRs for the same bounty issue
• Detect exhausted, paid, closed, and stale rounds before investing time

docs/agent-guide.md (+20 lines)

New Recovering from Rejection subsection:

• How to interpret mrwk:rejected labels as diagnostic feedback
• How to respond to mrwk:needs-info requests promptly
• Auditing your preflight process after a rejection
• Targeting different bounties or scopes

Evidence

• These are pure documentation additions — no code changes, no behavior changes
• All API endpoints referenced are documented elsewhere in the repo and verified against the live api.mrwk.ltclab.site host
• The preflight workflow follows the same patterns used by maintainers in docs/bounty-rules.md and by the submission_quality_gate.py script
• No overlapping scope with PR docs: clarify bounty submission hygiene #386: that PR updates the agent checklist, PR template fields, and bounty-rule submission guidelines. This PR adds API-level preflight examples and post-submission recovery guidance — distinct surfaces that together satisfy Bounty MRWK bounty: agent submission hygiene and claim-window docs #383's full scope

Test Evidence

• ruff format --check .
• ruff check .
• mypy app (no Python code changes)
• pytest (no test changes)
• python scripts/docs_smoke.py — docs-only change, template and examples updated

MRWK

Refs #383

Summary by CodeRabbit

• Documentation
  • Added guidance on recovering from rejections: how to interpret rejection labels, appropriate responses to needs-info, avoid resubmitting identical work, and when to target different bounties or scope.
  • Added pre-bounty preflight checks: steps to verify bounty award capacity, check active/expired attempt reservations, cross-reference open PRs, and avoid exhausted or stale rounds.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ab59e7db-05f2-4b58-b2fc-cd607b51e102

📥 Commits

Reviewing files that changed from the base of the PR and between 9a1128e and a4b245b.

📒 Files selected for processing (1)

• docs/api-examples.md

---

📝 Walkthrough

Walkthrough

Adds two documentation sections: pre-bounty read-only preflight checks (API and GitHub verification) and a “Recovering from Rejection” subsection explaining labels, when not to resubmit, and next steps after rejection.

Changes

Agent submission guidelines

Layer / File(s)	Summary
Pre-bounty preflight checks docs/api-examples.md	New section documenting read-only validation before submission: check bounty capacity via list/single-bounty endpoints (max_awards, awards_paid, awards_remaining, status), query active attempt reservations (optionally include expired for audits), cross-reference open PRs for the same bounty issue number, and a checklist to avoid exhausted/paid/stale rounds using live API and GitHub signals.
Recovering from rejection docs/agent-guide.md	New subsection explaining mrwk:rejected label interpretation, when not to resubmit the same work, how to respond to mrwk:needs-info, and guidance to audit preflight checks or target different bounties/scopes after rejection.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• MRWK bounty: agent submission hygiene and claim-window docs #383 — Both PRs modify docs/agent-guide.md to refine agent submission guidance within the contribution rules area.

Suggested labels

mrwk:accepted

Suggested reviewers

• weilixiong

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main changes: adding pre-bounty preflight checks and rejection recovery guidance to documentation, with explicit reference to Bounty #383.
Description check	✅ Passed	The description is comprehensive and well-structured, covering summary, detailed changes, evidence, test results, and MRWK reference. It follows the template structure and provides sufficient context about the documentation additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/api-examples.md`:
- Around line 589-592: The curl currently queries the issues endpoint which
returns both issues and PRs; change the preflight query to the PR-specific
endpoint by replacing "issues?state=open" with "pulls?state=open&per_page=50"
(or, if you must keep using the issues endpoint, filter the returned items by
presence of the pull_request field before applying the "Bounty `#N`"/"Refs `#N`"
checks) so only actual pull requests are scanned for overlapping scope.
- Line 586: Update the sentence in docs/api-examples.md that currently reads
“Open multiple PRs for the same bounty issue from different contributors is
normal for multi-award bounties, but you should avoid overlapping scope” to use
correct subject-verb agreement; change it to either “Opening multiple PRs for
the same bounty issue from different contributors is normal for multi-award
bounties, but you should avoid overlapping scope” or “Multiple open PRs for the
same bounty issue from different contributors are normal for multi-award
bounties, but you should avoid overlapping scope.”

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a52f328b-5794-4e6f-93b4-065004a7d762

📥 Commits

Reviewing files that changed from the base of the PR and between 04153ee and 9a1128e.

📒 Files selected for processing (2)

• docs/agent-guide.md
• docs/api-examples.md

[aiautotool]

I found two small documentation issues that should be fixed before this lands. The overall direction is useful for #383, and the changed docs pass the smoke check, but the PR example should avoid sending agents to an endpoint that mixes issues and PRs.

Findings:

• docs/api-examples.md:586 has a subject/verb agreement typo: “Open multiple PRs ... is normal”. Use “Opening multiple PRs ... is normal” or “Multiple open PRs ... are normal”.
• docs/api-examples.md:590-592 says to check open PRs, but the example queries /issues?state=open&per_page=50. GitHub’s issues endpoint returns both issues and pull requests, so agents following this literally can treat regular issues as overlapping PRs. Since this section is specifically PR preflight, use /pulls?state=open&per_page=50, or explicitly filter /issues results to objects with pull_request before scanning bodies.

Evidence checked:

• docs/api-examples.md added capacity, active-attempt, open-PR, and stale-round preflight guidance.
• docs/agent-guide.md added rejection/needs-info recovery guidance.
• The changes are docs-only and scoped to docs/api-examples.md and docs/agent-guide.md.

Local validation from a clean PR worktree:

• /Users/vkct/Documents/Codex/2026-05-26/s-d-ng-ki-n-th/mergework/.venv/bin/python scripts/docs_smoke.py -> docs smoke ok
• git diff --check origin/main...HEAD -> passed

No secrets, private security details, payout credentials, or MRWK price claims found in the reviewed diff.

[Karry2019web]

Fixed both review items:

1. Grammar fix: "Open multiple PRs ... is normal" → "Opening multiple PRs ... is normal"
2. Endpoint fix: Changed curl example from /issues?state=open to /pulls?state=open&per_page=50 to avoid mixing issues with PRs

Please re-review when convenient. 🙏