π The fast, Pythonic way to build MCP servers and clients.
Clarify maintainer review decisions (#5466)
Jeremiah Lowin2eefbcd83e35
diff --git a/.agents/skills/review-issue/SKILL.md b/.agents/skills/review-issue/SKILL.mdindex 4e17be91b..7c7963fad 100644--- a/.agents/skills/review-issue/SKILL.md+++ b/.agents/skills/review-issue/SKILL.md@@ -39,7 +39,7 @@ Assignment commits us to reviewing the PR, not to merging it. A gate closure is3. **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.-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.+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.5. **Check the contributor.** For an unfamiliar account, look at its public history:diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.mdindex 5f5af7cb9..61d79ee03 100644--- a/.agents/skills/review-pr/SKILL.md+++ b/.agents/skills/review-pr/SKILL.md@@ -11,17 +11,19 @@ For review-only tasks, assess and report; repair, push, and monitoring steps app## Procedure-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.+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. State whether this restores an established contract or proposes a behavior change. If the contract is unresolved, surface the precise maintainer decision and do not recommend 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. If the contract is unresolved, surface the precise maintainer decision and do not recommend approval or readiness on the strength of passing tests.-3. **Trace the cause and compatibility.** Read every changed file in context, its callers, producers and consumers, and shared abstractions. Check whether the fix changes the causal path or compensates elsewhere. Search for the same bug pattern and trace affected tools, resources, templates, and prompts; use canonical component identity. Compare omitted defaults, explicit overrides, errors, serialization, and supported configurations. State which existing inputs change behavior, why that is necessary, and any migration preserving the old behavior. Keep breaking changes out of a patch recommendation. Check API ergonomics, docs, and whether dependency minimums support newly used APIs; test the old minimum when compatibility is claimed and keep lockfile changes scoped.+ 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.++3. **Trace the cause and compatibility.** Read every changed file in context, its callers, producers and consumers, and shared abstractions. For a bug fix, state the causal ownership: the contract is X, the failure originates in Y, and this patch repairs Y. Check existing configuration, extension hooks, and shared abstractions before accepting new framework behavior. If the patch compensates elsewhere, explain why the owning layer cannot address the cause. Search for the same bug pattern and trace affected tools, resources, templates, and prompts; use canonical component identity. Compare omitted defaults, explicit overrides, errors, serialization, and supported configurations. State which existing inputs change behavior, why that is necessary, and any migration preserving the old behavior. Keep breaking changes out of a patch recommendation. Check API ergonomics, docs, and whether dependency minimums support newly used APIs; test the old minimum when compatibility is claimed and keep lockfile changes scoped.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, 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. 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.-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 remaining decisions separately from CI and bot status.+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.## GitHub evidence@@ -46,11 +48,13 @@ Keep the report proportional to the change, with these facts explicit:> **Verdict:** ready for maintainer consideration / changes needed / maintainer decision needed / validation pending β at `<head>`, against `<base>`.>-> **Contract:** promised behavior and supporting source; why this is a correction or a proposed change.+> **Scope and design:** change category, promised behavior and supporting source; whether it belongs in FastMCP and any precise maintainer decision still needed.+>+> **Implementation:** whether the patch repairs the causal layer, with consequential defects or competing-proposal selection.>> **Compatibility:** inputs whose behavior changes, adjacent behavior preserved, and any migration or release constraint.>-> **Evidence:** regression on base/head, neighboring checks, adversarial result or why it was not required, CI and bot status at this revision.+> **Validation:** regression on base/head, neighboring checks, adversarial result or why it was not required, CI and bot status at this revision. Distinguish a code approval with pending CI from a merge-ready recommendation.>> **Outstanding:** consequential findings, decisions, and checks still pending.