bug-catcher

name	bug-catcher
description	Audit a Go package in this repository for subtle correctness bugs, including both bugs inside the package and bugs in how the rest of the repository uses it. Optimized for Pebble- and CockroachDB-style code where invariants, iterator semantics, ownership, and API contracts matter more than style issues.
disable-model-invocation	true

You are running a multi-stage audit of a Go package.

The user will provide exactly one argument: a repo-relative path to a Go package directory.

Your goal is to produce a final report containing confirmed bugs only, ordered by severity, with no fix suggestions.

This skill is optimized for large Go storage/database codebases like Pebble and CockroachDB. Favor semantic correctness, invariants, and contract violations over stylistic critique.

Primary objective

Find bugs that are likely to pass unnoticed by a human reviewer, especially:

• typos that still compile but alter behavior
• wrong field / constant / comparer / option / bound / level / sequence number chosen
• subtle API misuse by callers
• semantic mismatches between comments, names, and implementation
• edge cases around iterator validity, bounds, exhaustion, and positioning
• ownership / aliasing / lifetime mistakes
• incorrect assumptions around zero values or sentinel values
• ordering mistakes
• concurrency / locking / callback / reentrancy mistakes
• stale invariants after refactors
• test coverage that appears convincing but fails to pin down the actual contract

Non-goals

• no style review
• no formatting nits
• no speculative “maybe” issues in the final report
• no patch suggestions
• no performance-only observations unless they imply a correctness bug

Required workflow

Stage 1: build package understanding

Start the package-understander subagent on the target package path.

Its output must be written to a durable artifact, not only held in conversational state.

Write to:

$TMPDIR/bug-catcher/<sanitized-package-path>/understanding.md

The understanding must capture:

• package purpose
• exported API
• key internal helpers and state transitions
• invariants and hidden assumptions
• important data representations
• ownership / lifetime expectations
• concurrency / synchronization expectations
• important tests and what they appear to specify
• key dependencies
• major callers in the repo
• what those callers appear to assume about this package
• bug-prone surfaces

Stage 2: generate candidate bugs

Start the candidate-generator subagent on the target package.

Pass it:

• package path
• understanding artifact path ($TMPDIR/bug-catcher/<sanitized-package-path>/understanding.md)
• output path: $TMPDIR/bug-catcher/<sanitized-package-path>/candidates.md

Stage 3: confirm each candidate independently

For each candidate, start a fresh bug-confirmer subagent.

Pass it:

• package path
• understanding artifact
• candidate description
• relevant files / symbols

Each confirmer must independently determine whether the issue is real, trying first to disprove it.

A candidate should only be confirmed if the evidence supports a specific semantic failure mode, not merely surprising or ambiguous code. When in doubt, mark it not-confirmed.

Each confirmation must return:

• verdict: confirmed / not-confirmed
• severity: critical / high / medium / low
• confidence: high / medium / low
• concise justification
• exact code references

Write one confirmation per file:

$TMPDIR/bug-catcher/<sanitized-package-path>/confirmations/<NNN>.md

Stage 4: final report

Produce a final report containing only confirmed bugs, sorted by severity, then confidence.

When ordering confirmed bugs, rank by:

1. semantic correctness impact, especially corruption or persistent wrong behavior
2. breadth of affected call paths
3. likelihood in realistic usage
4. confidence

For each confirmed bug include:

• severity
• short title
• category
• package path
• affected files / symbols
• concise explanation
• why it could slip past review
• evidence

Do not include fix suggestions. Do not include rejected candidates. Do not dilute the report with general observations.

Pebble / CRDB-specific hunting guidance

When auditing these kinds of codebases, pay extra attention to:

• iterator positioning, validity, lower/upper bounds, and exhaustion semantics
• ownership of byte slices, keys, values, buffers, and backing storage
• sequence-number visibility rules
• tombstone / range-key / masking / shadowing semantics
• comparer / split / separator / successor assumptions
• format-major-version or feature-gating assumptions
• state machines with implicit ordering requirements
• zero-value structs that are valid in some contexts but not others
• interaction between options structs and defaults
• cross-level or cross-batch assumptions
• internal iterators vs external iterator contract mismatches
• correctness assumptions encoded only in tests or comments
• call sites that accidentally rely on stronger guarantees than the package actually provides

How to inspect caller misuse

Search for and inspect:

• imports of the package
• constructors
• exported funcs and methods
• interface implementations and adapters
• tests that use the package
• wrappers that narrow or reinterpret semantics

For each important API surface, ask:

• what contract does the package actually provide?
• what contract do callers appear to assume?
• where do those differ?

Quality bar

The final output should read like a triaged bug docket for a senior Pebble/CRDB engineer:

• low noise
• evidence-backed
• focused on semantic defects
• conservative about confirmation
• ordered by severity