Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Keep review design decisions with maintainers (#5468)

Jeremiah Lowin486a6dcf697d
diff --git a/.agents/skills/review-issue/SKILL.md b/.agents/skills/review-issue/SKILL.md
index 7c7963fad..d5f637fba 100644
--- a/.agents/skills/review-issue/SKILL.md
+++ b/.agents/skills/review-issue/SKILL.md
@@ -5,10 +5,11 @@ description: Review an incoming external issue (and any gated-closed PR behind i
# Review an incoming issue
-This skill ends in one of two recommendations for the maintainer:
+This skill ends in a recommendation for the maintainer:
- **Assign**: the issue is valid, an external PR suits it, and a sound PR exists. Assign the author, which clears the gate, then review the code.
- **Decline**: close the open contribution, or leave a closed one closed, and explain why on the issue once authorized.
+- **Maintainer decision needed**: only when investigation leaves a concrete choice that materially changes supported behavior or ongoing support scope. State the affected scenario, competing outcomes, why protocol/docs/history/prior decisions do not settle it, and a recommendation. Ordinary reviewer uncertainty or implementation preferences do not qualify. The unresolved choice alone is not a reason to decline or formally request changes.
Assignment commits us to reviewing the PR, not to merging it. A gate closure is administrative, so a closed PR gets the same bar as an open one.
@@ -35,9 +36,9 @@ Assignment commits us to reviewing the PR, not to merging it. A gate closure is
gh pr view <pr> --repo PrefectHQ/fastmcp --comments
```
-2. **Decide whether the issue describes a bug.** Reproduce the MRE, then ask whether the behavior violates a contract FastMCP intends to hold. Behavior that only appears by mutating construction-time state or relying on internals is a property of the code, not a defect. The code shows what FastMCP does, not what it promises, so ask the maintainer "is X supported?" when the contract is unclear. Check `main`, duplicates, and prior maintainer decisions in related issues and closed PRs. If the issue is not a bug, recommend declining without reviewing the PR.
+2. **Decide whether the issue describes a bug.** Reproduce the MRE, then ask whether the behavior violates a contract FastMCP intends to hold. Behavior that only appears by mutating construction-time state or relying on internals is a property of the code, not a defect. The code shows what FastMCP does, not what it promises, so investigate the promised contract before escalating. Ask the maintainer only when a specific supported scenario requires a material policy choice that the protocol, docs, history, and prior decisions do not settle. Check `main`, duplicates, and prior maintainer decisions in related issues and closed PRs. If the issue is not a bug, assess its contribution category rather than treating surprising behavior alone as a defect.
-3. **Check the category against [the contribution policy](../../../docs/development/contributing.mdx#choose-a-contribution).** Simple bug fixes, docs, and auth providers are assignable. Enhancements need a maintainer-approved design in the issue first; approve the approach, then assign. Third-party integrations and sweeping changes without discussion are declined.
+3. **Check the category against [the contribution policy](../../../docs/development/contributing.mdx#choose-a-contribution).** Simple bug fixes, docs, and auth providers are assignable. Enhancements need a maintainer-approved design in the issue first; bring the precise decision and a recommendation to the maintainer, record the accepted approach, then assign. Maintainers own design opinions: do not require the contributor to obtain or settle the maintainer's preference. Once a direction is accepted, maintainers should make small corrections that align a nearly ready fix with established behavior under [review-pr](../review-pr/SKILL.md), rather than formally requesting changes for those finishing touches. Leave substantive rework to the contributor. Third-party integrations and sweeping changes without discussion are declined.
4. **Investigate the PR in context.** Read the full diff, then open each touched file. Trace the values and functions it changes to where they are produced and consumed. From the MRE, state in one line what was broken, where, and whether this change fixes it there. Compare with how adjacent code handles the same case, and check that the tests fail without the fix. Treat style issues as review comments; a wrong layer, a broken adjacent path, or an unfixed MRE changes the verdict. Apply [review-pr](../review-pr/SKILL.md)'s behavior classification, protocol check, and competing-proposal comparison before recommending a proposal. Keep scope and design acceptance separate from implementation quality and pending validation.
diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.md
index 61d79ee03..25bbf3d88 100644
--- a/.agents/skills/review-pr/SKILL.md
+++ b/.agents/skills/review-pr/SKILL.md
@@ -13,7 +13,9 @@ For review-only tasks, assess and report; repair, push, and monitoring steps app
1. **Establish the scope.** Read AGENTS.md, the contribution policy in [the development guide](../../../docs/development/contributing.mdx), the issue's full discussion, the entire diff against the merge base, and prior review threads and replies. Record the base and head revisions. Find related issues and PRs in all states, and inspect open PRs touching the same files for overlapping lines or behavior even when they do not link the issue. Distinguish released behavior, fixes already on main, and competing proposals. When proposals compete, record the issue reporter, original implementation author, maintainer direction, correctness, and distinct coverage. Recommend which proposal should survive and preserve carried-forward credit; submission order and green CI do not select the winner. Call a sound overlapping proposal redundant rather than spurious.
-2. **Establish the contract before judging the fix.** Use the protocol, released docs, history, and maintainer decisions to explain what FastMCP promises for the reported inputs. Existing code and tests are evidence of behavior, not sufficient proof that it is intended. A reproducer can demonstrate surprising behavior without demonstrating a bug; a regression test can assert the wrong result. Classify the change as a contract-restoring bug fix, intentional behavior change, public API addition or modification, documentation, or tests; a PR can span categories. Name existing inputs whose outcomes change, including defaults and explicit overrides. A bug title does not establish the category. Decide whether the behavior and ongoing support belong in FastMCP before assessing implementation quality. If the contract is unresolved, surface the precise maintainer decision and do not recommend approval or readiness on the strength of passing tests.
+2. **Establish the contract before judging the fix.** Use the protocol, released docs, history, and maintainer decisions to explain what FastMCP promises for the reported inputs. Existing code and tests are evidence of behavior, not sufficient proof that it is intended. A reproducer can demonstrate surprising behavior without demonstrating a bug; a regression test can assert the wrong result. Classify the change as a contract-restoring bug fix, intentional behavior change, public API addition or modification, documentation, or tests; a PR can span categories. Name existing inputs whose outcomes change, including defaults and explicit overrides. A bug title does not establish the category. Decide whether the behavior and ongoing support belong in FastMCP before assessing implementation quality. Resolve ordinary review uncertainty from the protocol, released docs, history, and prior maintainer decisions; make a recommendation within the established contract. Passing tests alone do not establish that contract.
+
+ Maintainers own design opinions. Escalate only a concrete product or compatibility choice that remains unresolved after investigation and materially changes supported behavior or the scope FastMCP commits to maintaining. Identify the supported scenario, the competing outcomes, why existing authority does not settle them, and your recommended direction. Ordinary implementation judgment, naming preferences, speculative edge cases, and uncertainty that further investigation can resolve are not reasons to stop for a decision. An actual unresolved policy choice is not a contributor defect; do not submit a formal changes-requested review solely because that choice is unsettled, or ask the contributor to obtain or settle it. Once the maintainer chooses, assess the implementation against that direction. When the intended behavior is established and the correction is small, make the localized repair within authorization rather than submitting a changes-requested review. Reserve formal changes requests for a materially wrong approach or behavior that needs rethinking; explain the concrete behavioral correction after the maintainer settles the direction.
For protocol-facing changes (wire fields, auth challenges, capabilities, errors, or cache semantics), cite the applicable specification revision and normative primary source. Distinguish what the protocol requires or permits, what the SDK implements or defaults, and what policy FastMCP chooses. SDK support alone does not settle framework policy; do not strengthen a protocol hint into a guarantee.
@@ -21,7 +23,7 @@ For review-only tasks, assess and report; repair, push, and monitoring steps app
4. **Verify behavior independently.** For bug fixes, use [python-tests](../python-tests/SKILL.md) to run the regression on the unchanged base and proposed head yourself. Confirm it fails for the claimed reason and asserts the intended value and type, not merely that a result exists. For other changes, verify the promised behavior with appropriate checks. Exercise neighboring supported paths sharing the changed branch. For shared dispatch, security boundaries, or behavior other components rely on, get an independent adversarial pass: give a fresh agent the PR and paths to investigate, have it run reproducers in a throwaway worktree, and retain confirmed findings. Repeat that pass after substantive rework. Record revisions and checks actually run; unavailable validation remains pending evidence.
-5. **Evaluate feedback and resolve findings.** Fetch CI, review summaries, inline threads, and replies together using the commands below. Evaluate CodeRabbit, Copilot, Codex, and maintainer feedback on its merits. Collect all independent consequential findings in one pass, with reachable triggers and consequences; do not repeat resolved or convincingly rebutted findings without new evidence. Avoid cosmetic blockers and speculative scope expansion. Within authorization, maintainer repairs should be localized finishing touches on a contribution whose scope and design are accepted and which is nearly ready. Substantive API, protocol, behavior, or architectural rework remains the contributor's responsibility: request changes rather than taking over, even when maintainer edits are enabled. For those small repairs, fix real defects together, verify adjacent behavior, run required checks, and push. Resolve verified fixes; reply with a reason when declining a finding if posting is authorized. Do not iterate indefinitely on hypothetical follow-ups.
+5. **Evaluate feedback and resolve findings.** Fetch CI, review summaries, inline threads, and replies together using the commands below. Evaluate CodeRabbit, Copilot, Codex, and maintainer feedback on its merits. Collect all independent consequential findings in one pass, with reachable triggers and consequences; do not repeat resolved or convincingly rebutted findings without new evidence. Avoid cosmetic blockers and speculative scope expansion. Within authorization, maintainer repairs should be localized finishing touches on a contribution whose scope and design are accepted and which is nearly ready. A nearly ready fix that only needs small corrections to match established behavior should be finished by the maintainer, including targeted regression coverage. After the maintainer settles the direction, substantive API, protocol, behavior, or architectural rework remains the contributor's responsibility; explain that work rather than taking over, even when maintainer edits are enabled. For the small repairs, fix real defects together, verify adjacent behavior, run required checks, and push. Resolve verified fixes; reply with a reason when declining a finding if posting is authorized. Do not iterate indefinitely on hypothetical follow-ups.
6. **Follow the current revision to a verdict.** A push invalidates evidence tied only to the old head. After publication or an update within the task, establish quiet monitoring using the host's scheduling capability; notify only on meaningful changes, decisions, failures, or completion, and pause after the terminal report. For a one-time review, report pending checks without creating an ongoing monitor unless requested. If persistent monitoring is unavailable, watch during the active task and state the limitation. Inspect failed CI logs before diagnosing or retrying; distinguish assertions, worker crashes, dependency resolution, and infrastructure failures. Reproduce supposedly unrelated failures on the base. Report scope and design acceptance, implementation correctness, and remaining validation separately. An approval with pending CI can be appropriate when the user has authorized it and the scope, design, and code are accepted; approval does not mean merge readiness. Pending CI cannot resolve an unsettled design decision, and a process gate is not a code defect.