Bug Hunt

Instrumentation Bug Hunting

Arguments

$ARGUMENTS - The library name, optionally followed by focus context.

Format: <library> [focus on <area>]

Examples:

• /bug-hunt redis — broad bug hunting across all redis functionality
• /bug-hunt redis focus on pub sub interactions — prioritize pub/sub patterns
• /bug-hunt mysql2 focus on prepared statements and transactions — prioritize those areas

Parsing: The first word of $ARGUMENTS is always the library name. Everything after it is the optional focus context. All references to <library> below mean this parsed first word — NOT the raw $ARGUMENTS string.

Library-to-GitHub-Repo Mapping

Use this mapping to clone the package source code for analysis:

E2E Test Variants

Each library has ESM and CJS variants. Use the CJS variant as the primary target for bug hunting:

Phase 0: Environment Setup

0.1 Parse and validate the arguments

Extract the library name (first word) and optional focus context (remaining words) from the arguments.

The library must be one of: fetch, firestore, grpc, http, ioredis, mongodb, mysql, mysql2, nextjs, pg, postgres, prisma, redis, upstash-redis-js.

If the library is invalid, list the valid options and stop.

If focus context is provided, it will guide Phases 1 and 2 to prioritize that area of the library's functionality.

0.2 Docker Setup (Claude Code Web only)

Check if Docker is running. If not, start it:

dockerd --storage-driver=vfs &>/tmp/dockerd.log &
# Wait for Docker to be ready
for i in $(seq 1 30); do
  docker info &>/dev/null 2>&1 && break
  sleep 1
done
docker info &>/dev/null 2>&1 || { echo "Docker failed to start. Check /tmp/dockerd.log"; exit 1; }

If Docker is already running, skip this step.

0.3 Clone the package source code (for analysis only)

If the library has a GitHub repo (see mapping above), clone it for reference:

git clone --depth 1 <repo-url> /tmp/<library-name>-source

This is read-only reference material — you will NOT modify this repo.

0.4 Create a working branch

Skip this step if you are already on a dedicated branch (e.g., in Claude Code Web where each session has its own branch).

git checkout -b bug-hunt/<library>-$(date +%Y-%m-%d)

Phase 1: Develop Understanding

If focus context was provided, prioritize your analysis around that area. For example, if the focus is "pub sub interactions", concentrate on pub/sub-related code paths in the instrumentation, tests, and package source.

1.1 Analyze the Instrumentation Code

Read the instrumentation code at:

src/instrumentation/libraries/<library>/Instrumentation.ts

Identify:

• Which functions from the package are patched/instrumented
• The patching strategy (what gets wrapped, when, and how)
• Any helper files in the same directory
• If focus context provided: Which patches relate to the focus area, and what's missing?

1.2 Analyze Existing E2E Tests

Review the CJS variant's test files:

• src/instrumentation/libraries/<library>/e2e-tests/cjs-<library>/src/index.ts — all test endpoints
• src/instrumentation/libraries/<library>/e2e-tests/cjs-<library>/src/test_requests.mjs — which endpoints are called

Understand what functionality is already tested and identify coverage gaps.

• If focus context provided: What tests already exist for the focus area? What's missing?

1.3 Analyze the Package Source Code

If you cloned the package source, read it to understand:

• The package's entry points and full API surface
• Functions that are currently patched vs functions that exist but aren't patched
• Alternative call patterns, overloads, and edge cases
• If focus context provided: Deep-dive into the focus area's API surface and usage patterns

Phase 2: Identify Potential Gaps

If focus context was provided, prioritize bugs related to that area. You may still note other potential issues, but test the focus area first.

Reason about potential issues. Consider:

• Untested parameters: Parameter combinations not covered by existing tests
• Alternative call patterns: Can patched functions be invoked differently (callbacks vs promises, different overloads)?
• Missing patches: Functions that should be instrumented but aren't
• Edge cases: Null/undefined values, empty results, large payloads, streaming, connection errors
• ORM/wrapper usage: Libraries like Sequelize, Knex, Prisma that wrap the base driver — are those call paths instrumented?
• Real-world usage patterns: How is the package typically used in production apps?

Produce a prioritized list of potential bugs to investigate.

Phase 3: Initialize Bug Tracking Document

Create BUG_TRACKING.md in the CJS e2e test directory:

# Path: src/instrumentation/libraries/<library>/e2e-tests/cjs-<library>/BUG_TRACKING.md

# <library> Instrumentation Bug Tracking

Generated: <current date and time>

## Summary

- Total tests attempted: 0
- Confirmed bugs: 0
- No bugs found: 0
- Skipped tests: 0

---

## Test Results

(Tests will be documented below as they are completed)

Phase 4: Write Tests and Verify Issues

For each potential bug, follow this workflow:

4.1 Initial Setup (Once)

Navigate to the CJS e2e test directory:

cd src/instrumentation/libraries/<library>/e2e-tests/cjs-<library>/

Start Docker containers:

docker compose up -d --build --wait

Install dependencies:

docker compose exec -T app npm install