/tdd-parity-review

description: Parity-focused review using grumpy-gopher to verify a branch faithfully implements a Python SDK PR with idiomatic Go
allowed-tools: Read, Grep, Glob, Bash, Agent, WebFetch

TDD Parity Review

> **REVIEW ONLY.** This command reports findings. It never makes changes. After presenting results, stop and let the user decide what to fix.

Spawns a `grumpy-gopher` agent to review the current branch against one or more Python SDK parity items.

**Two co-equal parity gates** are checked. Both are mandatory. A violation of either is a blocker:

1. **Observable-behavior parity with Python SDK** — wire format (JSON field names, constants, message shapes, CLI flags), public API surface (method/type/parameter names), and semantics (what each call does, what errors return, what fields populate). 2. **Idiomatic Go delivery** — the *shape* of the code that delivers the parity contract: context-first, `fmt.Errorf` with `%w` wrapping, nil-safety, small focused interfaces, gofmt/golangci-lint clean, gocyclo under 15, channel-based concurrency, zero-value usability, no unnecessary exports.

Parity is the *what*. Idiomatic Go is the *how*. Neither is negotiable; neither is a polish step. Mirroring Python *internals* is not a goal — when a Go idiom and a Python internal shape conflict, choose the Go idiom and record the deliberate divergence. Beyond the two gates, the reviewer also checks regressions, example coverage, comment hygiene, and docs reconciliation.

Usage

/tdd-parity-review [python-pr-numbers]

Examples:

• `/tdd-parity-review` — reviews all pending items on the current branch (auto-detected from tracker)
• `/tdd-parity-review 506` — reviews Python PR #506 specifically
• `/tdd-parity-review 506 516` — reviews both PRs

Step 1: Gather Context

Run these in parallel:

git diff main...HEAD --stat
git log main..HEAD --oneline
git diff main...HEAD -- <substantive Go files, exclude CLAUDE.md/auto-memory>

Read `docs/tracking/README.md` to get the spec for each target PR: expected types, field names, wire format, JSON tags, method signatures.

If `$ARGUMENTS` is empty, infer target PRs from the tracker: find items whose Go Status is `pending` and whose description matches files changed on this branch.

Step 2: Locate Python SDK Source

The Python SDK lives at `../claude-agent-sdk-python/src/claude_agent_sdk/`. Key files:

• `_internal/message_parser.py` - message parsing and wire format
• `types.py` - type definitions, field names, literals
• `_internal/query.py` - control protocol subtypes and request shapes
• `_internal/client.py` - client API surface

Read the relevant Python source for each target PR to establish ground truth. Do not assume field names or constant values - grep the Python source to confirm every single one.

Step 3: Build and Run Examples

Before spawning the reviewer, check the examples directory:

# Verify all examples still compile after branch changes
go build ./examples/...

# List examples and their entry points
ls examples/

For each example that compiles, attempt to run it with a short timeout to catch runtime panics or obvious breakage:

# Run each example binary briefly - they may need ANTHROPIC_API_KEY
# Note which ones succeed, which fail, and why (missing env, panic, etc.)

Document:

• Which examples compile cleanly
• Which examples fail to compile and why
• Which examples exercise functionality added by the target PRs
• Which examples are missing coverage for new functionality

Step 4: Spawn grumpy-gopher

Spawn a single `grumpy-gopher` agent with a self-contained prompt that includes:

1. **What this branch claims to implement** - list each Python PR number, its title, and the tracker spec

2. **Python SDK ground truth** - paste the relevant Python source snippets. Include:

• Every struct field name and its JSON key (grep `types.py` for each)
• Every constant string value (grep `_internal/query.py` for subtypes, `types.py` for Literals)
• Every CLI flag name (grep `_internal/cli.py` or equivalent)
• Every enum/Literal value

3. **Files to review** - the substantive changed files from Step 1

4. **Review mandate** — two co-equal mandatory gates, followed by cross-cutting concerns. The two gates are NOT ordered; failing either is a blocker. The reviewer reports findings under both gates with equal severity weight.

Gate 1 — Observable-behavior parity with Python SDK (mandatory)

• **100% wire format audit** - for every struct with JSON tags, verify each field name against Python source. For every constant, verify the actual string value (not just the Go name) against Python. For every control protocol subtype, verify against `_internal/query.py`. Do not assume - grep and confirm. Flag any field name, constant value, or subtype that cannot be confirmed from Python source.

• **Public API surface** - does the Go shape match Python's observable behavior? Method/type/parameter/return names, optional vs required field discrimination, error types returned, fields populated on success vs failure. Internal mechanics may differ; observable surface may not.

• **Semantics** - same inputs produce equivalent outputs; same edge cases (nil/None, empty, malformed) produce equivalent behavior; same env-var/config knobs have equivalent effects.

Gate 2 — Idiomatic Go delivery (mandatory)

The shape of the Go code is itself a parity gate. Observable behavior matching Python is necessary but not sufficient — the code that delivers that contract must look like Go a senior Go reviewer would write, not like Python translated into Go syntax. Flag at the same severity as wire-format violations:

• **Context-first** — every blocking exported function accepts `context.Context` as the first parameter
• **Error wrapping** — `fmt.Errorf("...: %w", err)` for chains; sentinel errors only when callers need `errors.Is`
• **Nil-safety** — every pointer dereference is guarded or i