review-issue

---
name: review-issue
description: Review an incoming external issue (and any gated-closed PR behind it) and decide whether to assign the contributor or decline. Use when the maintainer says "look at this issue", "review issue #N", "should we take this", or asks whether to assign someone. Assigning the author auto-reopens their PR for normal review. This is the entry point for incoming-issue triage — distinct from review-pr, which assesses the full change and follows CI and review feedback.
---

# Review an incoming issue

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.

## How the gate works

[require-issue-link.yml](../../../.github/workflows/require-issue-link.yml) checks every external PR:

- It needs `Fixes/Closes/Resolves #N`. PRs without a valid link are closed.
- A linked PR stays open with a failing check until its author is assigned to that issue. Issues labeled `prs welcome` waive assignment but still need the link.
- Assigning the author (`gh issue edit N --add-assignee <login>`) re-runs the check and reopens a gate-closed PR. If that run fails, the gate misbehaved: investigate the run rather than re-assigning.
- Maintainer PRs are exempt, and so are authors with the `trusted-contributor` label. Reopening a PR by hand or removing `missing-issue-link` applies a sticky `bypass-issue-check`, so prefer assignment.
- `marvin-triage-issue`, `marvin-dedupe-issues`, `auto-close-duplicates`, and `auto-close-needs-mre` have usually commented already. Read them as leads.

## Procedure

1. **Orient.** Read the issue, its bot comments, and every PR that references it, in all states:

   ```bash
   gh issue view N --repo PrefectHQ/fastmcp \
     --json number,title,state,author,body,labels,assignees,comments
   gh pr list --repo PrefectHQ/fastmcp --state all --search "#N in:body" \
     --json number,title,state,author,url,labels
   gh pr view <pr> --repo PrefectHQ/fastmcp --json title,body,labels,files,additions,deletions
   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 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; 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.

5. **Check the contributor.** For an unfamiliar account, look at its public history:

   ```bash
   gh api users/<login>
   gh search prs --author <login> --limit 20 --sort created --order desc \
     --json repository,title,state,createdAt,url
   ```

   Merged fixes elsewhere and substantive replies to reviewers show follow-through. Decline obvious spam or unattended automation: mass unrelated boilerplate, repeated nonresponsive replies. A new account, a sparse profile, or disclosed AI assistance is not a reason to decline. When evidence is thin, lean toward goodwill for a sound, scoped contribution and mention the uncertainty.

6. **Recommend.** Give the maintainer the verdict, one or two sentences of reasoning, and the exact command. Act within existing authorization and bring borderline calls back.

## Acting on the verdict

**Assign:**

```bash
gh issue edit N --repo PrefectHQ/fastmcp --add-assignee <login>
```

Confirm the `require-issue-link` run passes and the PR reopens, then review it and follow CI and feedback with [review-pr](../review-pr/SKILL.md). If the PR's head branch was deleted, assignment cannot reopen it; the workflow asks the author for a fresh PR.

**Decline:** with authorization, comment on the issue with the reason and the relevant contribution-policy section. Write the body to a file first:

```bash
gh issue comment N --repo PrefectHQ/fastmcp --body-file /tmp/triage-reply.md
```

## Check before finishing

The recommendation names the contract the issue does or does not violate, the layer where the cause lives, and whether the PR fixes it there.

More agent context in jlowin/fastmcp

12 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• PrefectHQ/fastmcp28k