/reproduce-bug

name: reproduce-bug
description: >-
  Reproduce a reported bug in googleapis/mcp-toolbox and decide whether it is
  real, delivering an evidence-backed verdict: confirmed, already fixed,
  misconfiguration, client-side, works as intended, not reproducible, or
  blocked. Use whenever a maintainer asks you to reproduce, verify, confirm, or
  investigate a bug report, asks "is this a real bug", "can you repro this",
  "does this still happen", or pastes an mcp-toolbox bug issue or stack trace to
  check. PROPOSE-ONLY: reproduces locally and reports; never comments on,
  labels, or closes the issue.

Reproduce a Bug Report (mcp-toolbox)

Scope: `googleapis/mcp-toolbox`

About half of reported bugs are not bugs in Toolbox server code: they are misconfiguration, a client-side problem, or something already fixed in a version the reporter has not upgraded to. So the job is not "make it fail", it is to reach a **defensible verdict at the lowest cost**. Work cheapest-first and stop the moment the evidence settles it. Building a full reproduction for something a one-line version check would have explained is the main way this goes wrong.

The Evidence Rule

**Every factual claim MUST cite evidence**: a `file:line`, a commit SHA, a version string, or the exact command and its output. Otherwise mark it `[UNVERIFIED]` and say what would confirm it.

Cite `file:line` in **your findings**, where the claim is about the tree as it is now. This skill's own pointers name files and symbols instead, since line numbers go stale between releases while symbols survive refactors. Resolve one with `grep -rn '<symbol>' --include="*.go"` and read it before citing a line.

Reproducing a bug proves it exists. Failing to reproduce proves much less, and only counts if the attempt was valid, so word the two differently.

Verdicts

Every run ends in exactly one:

| Verdict | Means | |---|---| | `confirmed` | Reproduced on current `main`. Real, still open. | | `already-fixed` | Reproduces on their version, not on `main`. Needs a release note or a link to the fix. | | `misconfiguration` | Their config or environment. | | `client-side` | In an SDK, CLI, or LLM client, not the server. Often belongs in another repo. | | `works-as-intended` | Deliberate behaviour, frequently a breaking change they have not read. | | `not-reproducible` | The attempt was valid and it did not fail. | | `blocked` | Needs infrastructure or credentials you do not have. Say exactly what. |

1. Pin the claim down

Read the issue and all comments before touching code.

gh issue view <n> --repo googleapis/mcp-toolbox --json number,title,body,author,labels,comments,createdAt

Extract, noting what is missing:

• **Version.** Highest-value field. `1.9.0+binary.linux.amd64` is usable;

"latest", a `:latest` tag, or blank are not.

• **The full config.** Reporters routinely paste only `sources:` when the fault

is in `tools:`.

• **The verbatim error**, not a paraphrase, with `--log-level DEBUG` output if

it exists.

• **Transport and client.** Direct `curl`, an SDK, Gemini CLI, an IDE? The bug

template's `Client` field is often an unfilled `<placeholder>`.

• **Expected versus actual**, separately. A report that says only what happened

may be a disagreement about intent.

State the claim in one falsifiable sentence: *given config X, action Y produces Z, and should produce W.* If you cannot write it, you do not yet know what to reproduce, and that is the finding.

**Check it is not already answered.** Search duplicates and scan `git log`/`git blame` for a fix that landed quietly. Closed issues carry almost no signal: nearly all closed bugs here are closed `COMPLETED` whether or not they were real, so read the thread. If a maintainer already diagnosed it, still reach your own verdict, then say whether you agree.

2. Run the cheap discriminators

Check the report against these shapes before standing anything up. Each is seconds of work; they are ranked by how often they fire.

| Shape | Recognise it by | |---|---| | **Wrong tool type** | A tool whose type is a *source* type, missing the `-sql` or `-execute-sql` suffix. Fails at startup, before any connection. | | **Version skew** | An unknown-field or missing-feature error for something the docs describe. Docs track `main`; their binary lags. | | **Client-side** | The failure surfaces in an SDK, CLI, or IDE frame, or against `/api/*` while MCP semantics are expected. | | **Parameter semantics** | The placeholder sits in an identifier position (`FROM $1`) rather than a value position (`WHERE id = $1`). | | **Deliberate behaviour change** | It broke at an upgrade, and a flag now gates what used to be on by default. | | **Database-side** | The same statement with the same credentials fails outside Toolbox too. | | **Credential escaping** | A password or `${ENV_VAR}` holding characters that need escaping. |

The table is only an index of what to suspect. When a row plausibly matches, read that section of [references/discriminators.md](references/discriminators.md) for how to confirm it, the fix, and the traps, including which shapes are sometimes real bugs.

**Trace error text rather than matching it from memory**, since wording changes between releases and their string is evidence about *their* build:

grep -rn '<distinctive fragment>' --include="*.go" internal/ cmd/   # where it is raised now
git log -S '<their exact error text>'                             # when the wording changed

No grep hit means version skew, not an invented error: their wording predates `HEAD`, and `git log -S` dates the build and finds what replaced it.

One question ranks above every shape: **does the failure happen before or after the source connects?** Config parsing, type validation, and manifest generation run before any connection, so they reproduce with zero infrastructure no matter which exotic database the report names.

3. Climb only as far as you need

Start at the lowest ru